@togrulzade/exg
v2.0.0
Published
Laravel-inspired Express.js MVC project generator
Readme
EXG — Express MVC Generator
Laravel-ə bənzər qovluq quruluşu olan Express layihəsi yaradan CLI. Üç seçim var: Prisma (main branch), Sequelize (sequelize) və Mongoose (mongoose). İnteraktiv suallar Azərbaycan dilindədir.
Lokal quraşdırma
Node.js 22+ istifadə et. Şablonun lokal nüsxəsi üçün Git də lazımdır.
cd exg-cli
npm ci
npm link
st --helpnpm link bu qovluğu kompüterində st əmrinə bağlayır. Kod dəyişəndə əmr həmin yeni kodu işlədir.
İstifadə
Yeni layihə yaratmaq üçün:
st
st my-api
st my-api --orm prisma
st another-api --orm sequelize
st mongo-api --orm mongooseTerminalda layihə adından və ORM seçimindən sonra database sualları gəlir. --orm prisma versən, yalnız ORM sualı keçilir; baza məlumatları yenə soruşulur.
Ad kiçik latın hərfi və ya rəqəmlə başlamalıdır. Yalnız a-z, 0-9, - istifadə et. Mövcud qovluq, fayl və ya simvolik link üzərinə yazılmır.
GitHub-a göndərmədən lokal şablonla işləmək üçün iki repozitoriyanın olduğu ana qovluqda:
st my-api --orm prisma --template ./express-mvc-starter
st sql-api --orm sequelize --template ./express-mvc-starter
st mongo-api --orm mongoose --template ./express-mvc-starterLokal seçim seçilmiş branch-in son commit-ini götürür. Şablondakı commit olunmamış dəyişikliklər, .env, node_modules və Git tarixçəsi yeni layihəyə köçürülmür. Şablonun hazırda açıq branch-i dəyişmir. Şablonda gizli faylları heç vaxt commit etmə.
Generator package.json və mövcuddursa package-lock.json içində ad və versiyanı dəyişir. Versiya 0.1.0, layihə isə private: true olur. Seçdiyin bağlantı .env-ə yazılır. Sequelize driver-i dəyişəndə npm vasitəsilə lock faylı yenilənir; bunun üçün registry bağlantısı lazımdır. Paketlər hələ quraşdırılmır, database yaradılmır və server başlamır.
Database seçimi və bağlantı
Məsələn, MySQL ilə Prisma layihəsi:
st shop-api --orm prisma --database mysqlSuallarda Enter bassan bu dəyərlər götürülür. Host, port, istifadəçi, şifrə və baza adını özün dəyişə bilərsən.
| Database | Hansı ORM-də? | Host | Port | İstifadəçi | Şifrə | | --- | --- | --- | --- | --- | --- | | PostgreSQL | Prisma, Sequelize | localhost | 5432 | postgres | boş | | MySQL | Prisma, Sequelize | localhost | 3306 | root | boş | | MariaDB | Prisma, Sequelize | localhost | 3306 | root | boş | | SQLite | Prisma, Sequelize | lazım deyil | lazım deyil | lazım deyil | lazım deyil | | MongoDB | Mongoose | localhost | 27017 | boş | boş |
Boş şifrə serverinin həqiqi şifrəsi demək deyil. EXG serverində istifadəçi və şifrə yaratmır. MySQL-də root üçün hansı şifrəni qoymusansa, sualda onu yaz. PostgreSQL-də adətən istifadəçi postgres olur; bu dəyəri də dəyişmək olar.
Baza adı layihə adından götürülür: shop-api → shop_api (maksimum 63 simvol). SQLite üçün başlanğıc fayl ./shop_api.db olur. Prisma-da bu yol prisma/ qovluğuna, Sequelize-də layihənin kökünə nəzərəndir. Fayl adını və alt qovluğunu dəyişmək olar, məsələn ./data/dev.db. SQLite üçün ayrıca server və şifrə soruşulmur.
Şifrə gizli daxil edilir. URL-də problem yaradan @, #, :, $ kimi simvollar generator tərəfindən kodlaşdırılır. Şəxsi bağlantın yalnız .env-ə yazılır; .env.example lokal və şifrəsiz nümunə saxlayır. .env Git-ə daxil edilmir.
MongoDB-də istifadəçini boş saxlasan, şifrəsiz lokal bağlantı hazırlanır. İstifadəçi yazsan, şifrə və authSource da soruşulur. authSource istifadəçinin yaradıldığı bazadır, başlanğıc dəyəri admin-dir.
Parametrləri birbaşa da verə bilərsən:
# Portu və istifadəçini dəyiş; çatışmayan məlumatlar soruşulacaq
st shop-api --orm prisma --database mysql --db-port 3307 --db-user app_user
# Bütün sualları keç; şifrə boş, qalan sahələr standart olsun
st local-api --orm prisma --database sqlite --yes
# PostgreSQL bağlantısının parametrləri
st report-api --orm sequelize --database postgresql \
--db-host localhost --db-port 5433 --db-user postgres --db-name reports --yes--yes (-y) verilsə, çatışmayan sahələr üçün başlanğıc dəyərlər istifadə olunur; ORM verilməyibsə Prisma seçilir. Layihə adı yenə lazımdır. İnteraktiv terminal olmayan mühitdə layihə adı və ORM verilməlidir; baza sahələri soruşulmadan başlanğıc dəyərlərini alır. Avtomatlaşdırmada şifrəni secret/env vasitəsilə EXG_DB_PASSWORD dəyişəninə ver. Şifrəni əmr tarixçəsinə salmamaq üçün --db-password parametri yoxdur.
Bu quraşdırma yeni layihə yaradılarkən edilir. Mövcud layihədə host, port, istifadəçi və şifrəni .env-də dəyiş. Baza növünü sonradan dəyişmək üçün ORM schema-sı, driver və migration-lar da uyğunlaşdırılmalıdır.
Prisma üçün həm schema.prisma provider-i, həm ilkin User migration-ı, həm də migration_lock.toml seçilmiş bazaya uyğun hazırlanır. MariaDB Prisma-nın mysql provider-indən istifadə edir. Hazır SQL faylları Prisma 5.22 migrate diff ilə yaradılıb. Xüsusi model və migration-ları olan lokal Prisma şablonunun başqa provider-ə çevrilməsi qəbul edilmir; generator məlumatı səssiz itirməmək üçün xəta verir.
Sequelize üçün runtime bağlantısı və database/config.cjs eyni dialekti istifadə edir. Müvafiq paket (pg, mysql2, mariadb və ya sqlite3) və lock faylı hazırlanır. SQLite faylları .gitignore-a əlavə olunur.
Prisma 5-də SQLite migration-ından əvvəl baza faylı mövcud olmalıdır. Generator scripts/prepare-sqlite.js və predb:migrate / predb:deploy npm hook-larını əlavə edir. Aşağıdakı npm əmrləri çatışmayan qovluğu və faylı hazırlayır; mövcud baza silinmir. Bu, layihəni sonradan Git-dən götürəndə də işləyir.
Layihə yaranandan sonra:
cd my-api
npm install
# .env hazırdır; server bazası seçmisənsə, əvvəl onu yarat və serverini başlat
npm run db:generate
npm run db:deploy
npm run devBu əmrlər Prisma üçündür. Sequelize üçün npm run db:migrate, Mongoose üçün isə işləyən MongoDB serveri lazımdır. Hər yaradılan layihənin DATABASE.md faylında seçdiyin bazaya uyğun addımlar var.
Şəbəkə və ya şablon hazırlama xətası olduqda hədəf layihə qovluğu yaradılmır. Son fayl köçürülməsi zamanı disk xətası olarsa qismən qovluq qala bilər; CLI xəta verir və mövcud məlumatları avtomatik silmir.
Controller və router yaratmaq
Yaratdığın Express layihəsinin içində:
cd my-api
st make:controller HomeControllerAna qovluqdan da işlədə bilərsən:
st make:controller HomeController --project ./my-apiƏmr bunları hazırlayır:
src/controllers/HomeController.js:static async index(req, res, next)metodu.src/routes/homeRoutes.js:GET /route-u controller-inindexmetoduna bağlıdır.src/routes/index.js: router import edilir və/homeyoluna qoşulur. Standart EXG tətbiqində ünvanGET /api/homeolur.
index daxilində TODO var və başlanğıcda 501 Not implemented JSON cavabı verir; metodu boş saxlayıb sorğunu cavabsız qoymur. Həmin hissəyə öz kodunu yaz.
st make:controller Home də işləyir. UserProfileController üçün userProfileRoutes.js və /user-profile yaranır. Qovluqlu adlar (Admin/HomeController) dəstəklənmir.
Mövcud faylların üzərinə yazılmır; eyni route yolu və import adı təkrar yaradılmır. Əmr ESM Express layihəsi və standart Router() + export default router quruluşu gözləyir. Standart quruluş tapılmazsa dəyişiklik etmədən xəta verir. Mövcud middleware və route sırası saxlanılır; yeni route default export-dan əvvəl qoşulur. Əsas router-də əvvəlcədən bütün yolları tutan 404/catch-all route varsa onun sırasını ayrıca nəzərə al.
Yalnız fayl yaradırsan, database əməliyyatı və migration işləmir. Lokal npm link istifadə edirsənsə yeni əmr dərhal əlçatandır.
Service yaratmaq
Biznes məntiqini (database sorğuları, hesablamalar, cache) controller-dən ayırmaq üçün:
st make:service UserService
# və ya: st make:service User --project ./my-apisrc/services/UserService.js yaranır. src/services qovluğu yoxdursa yaradılır, mövcud faylın üzərinə yazılmır:
export class UserService {
static async all() {
// TODO: Bu metodun məntiqini yaz.
return [];
}
}Controller-də istifadəsi:
import { UserService } from '../services/UserService.js';
export class UserController {
static async index(req, res, next) {
try {
const users = await UserService.all();
res.json({ success: true, data: users });
} catch (error) {
next(error);
}
}
}Controller yalnız sorğunu oxuyur və cavab qaytarır; data ilə iş service-də olur. Belə olduqda eyni məntiqi başqa controller-dən, admin paneldən və ya testdən də çağırmaq olur.
Request (validation) yaratmaq
Laravel-dəki make:request (FormRequest) kimi:
st make:request StoreProductRequest
# və ya: st make:request StoreProduct --project ./my-apisrc/requests/StoreProductRequest.js yaranır. Qaydaları zod ilə yaz:
export const StoreProductSchema = z.object({
name: z.string().trim().min(2).max(100),
price: z.coerce.number().positive(),
categoryIds: z.array(z.coerce.number().int().positive()).default([]),
});
export default validate(StoreProductSchema);Router-də middleware kimi istifadə et:
import StoreProductRequest from '../requests/StoreProductRequest.js';
router.post('/', StoreProductRequest, ProductController.store);Qaydalar ödənməsə controller-ə çatmadan 422 və sahə xətaları qaytarılır. Uğurlu olsa req.body təmizlənmiş datadır (trim, coerce, default tətbiq olunub). z.object-də yazılmayan sahələr req.body-dən silinir, ona görə qaydaları yazmadan istifadə etmə.
validate @st/http paketindən gəlir (köhnə strukturlu layihələrdə src/middlewares/validate.js yoxdursa yaradılır). Layihədə zod olmalıdır. Mövcud faylın üzərinə yazılmır. Validation yalnız req.body üçündür.
Seeder yaratmaq (Prisma)
Laravel-dəki make:seeder kimi:
st make:seeder BrandSeeder
# və ya: st make:seeder Brand --project ./my-apiƏmr bunları edir:
prisma/seeders/BrandSeeder.jsyaradır.recordssiyahısına data yaz, seeder hər biriniprisma.brand.upsert()ilə yazır:uniqueBysahəsinə (defaultname) görə yoxdursa yaradır, varsa toxunmur. Bu sahə schema-da@uniqueolmalıdır.prisma/seed.js(Laravel-dəkiDatabaseSeeder) faylında seeder-i import edir vəconst seeders = [...]siyahısının sonuna əlavə edir. Fayl yoxdursa yaradılır.package.json-da yoxdursadb:seedscript-i vəprisma.seedayarı əlavə olunur. Mövcud dəyərlərə toxunulmur.
İşlətmək: npm run db:seed. npx prisma migrate reset (Laravel-dəki migrate:fresh --seed) də sonda seed işlədir, amma bazadakı bütün datanı silir.
Seeder-lər seeders siyahısındakı sırayla işləyir: əlaqəli modellər (məsələn Product → Brand) asılı olduqları modeldən sonra gəlməlidir. Seeder-i təkrar işlətmək təhlükəsizdir, dublikat yaranmır. Modelin unikal sahəsi name deyilsə (məsələn email, slug), uniqueBy dəyərini dəyiş.
Mövcud seeder faylının üzərinə yazılmır. seed.js gözlənilən quruluşda deyilsə heç bir fayl dəyişdirilmədən xəta verilir. Sequelize və Mongoose şablonları üçün hələ dəstəklənmir.
Queue və job (BullMQ + Redis)
Laravel-dəki queue və make:job kimi:
st install:queue
npm install
st make:job SendWelcomeEmailRedis işləməlidir (macOS: brew install redis && brew services start redis). Ünvan .env-dəki REDIS_URL-dən götürülür.
Job yazmaq (src/jobs/SendWelcomeEmail.js, Laravel-dəki handle()):
export default async function SendWelcomeEmail({ userId }, job) {
const user = await prisma.user.findUnique({ where: { id: userId } });
// email göndər...
}Göndərmək (Laravel-dəki SendWelcomeEmail::dispatch(...)):
import { dispatch } from '@st/queue';
import SendWelcomeEmail from '../jobs/SendWelcomeEmail.js';
await dispatch(SendWelcomeEmail, { userId: user.id });
await dispatch(SendWelcomeEmail, { userId: user.id }, { delay: 60_000 }); // 1 dəqiqə sonraWorker-i işə salmaq (Laravel-dəki php artisan queue:work), server-dən ayrı terminalda:
npm run queue:dev # development: fayl dəyişəndə yenidən başlayır
npm run queue:work # productionƏmrlər bunları edir:
install:queue:src/@st/queuepaketini (dispatch,startWorker),src/jobs/index.js(job siyahısı) vəsrc/worker.jsyaradır;package.json-abullmq,ioredis,queue:workvəqueue:devəlavə edir;REDIS_URLyoxdursa.env-ə yazır. Queue shutdown zamanı özünü bağlayır (@st/core),src/server.jsdəyişdirilmir. Sonranpm installişlət ki,@st/queuelink olunsun. Köhnə strukturlu layihələrdə (src/@styoxdursa) əvvəlki kimisrc/queues/index.jsyaradılır vəsrc/server.js-də shutdown-acloseQueue()qoşulur.make:job:src/jobs/<Ad>.jsyaradır vəsrc/jobs/index.js-də qeydiyyata alır. Worker job-u funksiyanın adına görə tapır, ona görə funksiyanın adını dəyişmə.
Davranış:
- Xəta atan job 3 dəfəyə qədər yenidən cəhd edilir (5s, 10s, 20s).
dispatch-in 3-cü arqumenti ilə dəyişmək olar:{ attempts: 5 }. - Queue bağlantısı ilk
dispatch-da açılır: testlər və Redis-siz server normal başlayır. Redis 5 saniyədə cavab verməsədispatchxəta atır (QUEUE_DISPATCH_TIMEOUT_MS). - Redis açarları layihənin adı ilə başlayır (
my-api:default:...), ona görə bir neçə layihə eyni Redis-i paylaşa bilər (QUEUE_PREFIX,QUEUE_NAME). - Job-a bütöv obyekt yox, id göndər: data Redis-də JSON kimi saxlanılır, ən son datanı job-da bazadan oxu.
- Worker
Ctrl+C/SIGTERMalanda işləyən job-ların bitməsini gözləyib çıxır.QUEUE_CONCURRENCY(default 5) eyni vaxtda neçə job işlədiyini təyin edir.
JWT authentication quraşdırmaq (Prisma)
st install:jwt
# və ya: st install:jwt --project ./my-apiSonra:
npm install
npm run db:migrate -- --name add_user_passwordHazır endpoint-lər:
| Endpoint | Nə edir |
|---|---|
| POST /api/auth/register | { name, email, password } → istifadəçi yaradır, { user, token } qaytarır |
| POST /api/auth/login | { email, password } → { user, token } |
| GET /api/auth/me | Token sahibini qaytarır |
Route qorumaq üçün requireAuth middleware-ini əlavə et; daxil olan istifadəçi req.user-dədir:
import { requireAuth } from '../middlewares/auth.js';
router.post('/', requireAuth, ProductController.store);Sorğularda token header kimi göndərilir: Authorization: Bearer <token>.
Əmr bunları edir:
- Yaradır:
src/config/auth.js,src/services/AuthService.js,src/middlewares/auth.js,src/controllers/AuthController.js,src/routes/authRoutes.js,src/requests/RegisterRequest.js,src/requests/LoginRequest.js,test/auth.test.js. Requestsvalidate-i@st/http-dən götürür (köhnə strukturda yoxdursasrc/middlewares/validate.jsyaradılır). src/routes/index.js-də/authroute-unu qoşur.Usermodelinəpassword String?əlavə edir. Şifrə Node-unscryptfunksiyası ilə hash olunur.src/@st/database/index.js-də (köhnə strukturdasrc/config/db.js)new PrismaClient({ omit: { user: { password: true } } })yazır: şifrə hash-i heç bir sorğuda (məsələnfindMany()) qaytarılmır. Prisma 6.2-dən köhnə versiyalarda schema-yapreviewFeatures = ["omitApi"]də əlavə olunur..env-ə təsadüfiJWT_SECRETvəJWT_EXPIRES_IN=1d,.env.example-a boş nümunə yazır.package.json-ajsonwebtokenəlavə edir.
Mövcud faylların üzərinə yazılmır. Layihə gözlənilən quruluşda deyilsə (məsələn db.js-də tək new PrismaClient() yoxdursa və ya User modelində artıq password varsa) heç bir fayl dəyişdirilmədən xəta verilir. Sequelize və Mongoose şablonları hələ dəstəklənmir.
Token 1 gün etibarlıdır və bu müddətdə ləğv edilmir (logout və refresh token yoxdur). Production-da login üçün rate limit (məsələn express-rate-limit) əlavə et.
GitHub və npm-dən quraşdırma
GitHub-dan quraşdırmaq üçün:
npm i -g github:togrulzade/exg-cli
# npm-ə dərc edilibsə:
npm i -g @togrulzade/exgGitHub repozitoriyası: TogrulZade/exg-cli. npm-dən quraşdırma yalnız paket npm-ə dərc edilibsə işləyir.
Yoxlama
npm test
npm audit
npm pack --dry-runTestlər GitHub-a çıxmadan branch seçimini, yaradılan faylları, lokal Git şablonunu, yanlış adları, mövcud qovluğun qorunmasını və xəta hallarını yoxlayır. giget GitHub yükləməsi üçün istifadə olunur. Köhnə 1.x versiyasındakı tar asılılığının məlum boşluqlarına görə 3.x seçilib.
API mənbələri: giget, Prisma bağlantı URL-ləri, Sequelize driver-ləri.
