@shys/crud 1.0.1-beta.0 → 1.0.1-beta.2

package/README.md

@@ -0,0 +1,342 @@
+# @shys/crud
+
+MidwayJS v4 模块化 CRUD CLI 代码生成器，支持 TypeORM / Sequelize / MikroORM，支持配置文件和自定义模板。
+
+## 安装
+
+```bash
+# 全局安装
+npm install -g @shys/crud
+
+# 或项目内安装
+npm install -D @shys/crud
+```
+
+## 快速开始
+
+```bash
+# 交互式运行
+npx @shys/crud
+
+# 完整参数
+npx @shys/crud --module home --table sys_user --src ./src
+```
+
+### 配置到 package.json
+
+在项目的 `package.json` 中添加 `scripts` 命令，方便团队成员快速使用：
+
+```json
+{
+  "scripts": {
+    "crud": "shys-crud",
+    "crud:entity": "shys-crud --only-entity",
+    "crud:dry": "shys-crud --dry-run",
+    "crud:user": "shys-crud --module system --table sys_user --force",
+    "crud:order": "shys-crud --module order --table order_info --force"
+  },
+  "devDependencies": {
+    "@shys/crud": "^1.0.0"
+  }
+}
+```
+
+配置后使用方式：
+
+```bash
+# 交互式运行（推荐，可按需填写参数）
+npm run crud
+
+# 只生成 entity
+npm run crud:entity
+
+# 模拟运行预览（不实际写文件）
+npm run crud:dry
+
+# 生成指定表的完整 CRUD（已预定义 module 和 table）
+npm run crud:user
+npm run crud:order
+```
+
+如果使用 pnpm：
+
+```bash
+pnpm crud
+pnpm crud:user
+```
+
+> **提示**：推荐将常用的表配置成独立脚本（如上面的 `crud:user`、`crud:order`），配合 `--force` 可直接覆盖重新生成，配合 `crud.config.ts` 配置文件使用体验更佳。
+
+生成的目录结构：
+
+```
+src/modules/home/
+├── entity/
+│   └── sysUser.entity.ts
+├── dto/
+│   └── sysUser/
+│       ├── create.dto.ts
+│       ├── update.dto.ts
+│       ├── replace.dto.ts
+│       ├── query.dto.ts
+│       └── index.ts
+├── vo/
+│   └── sysUser/
+│       ├── sysUser.vo.ts
+│       ├── sysUserList.vo.ts
+│       └── index.ts
+├── service/
+│   └── sysUser.service.ts
+└── controller/
+    └── sysUser.controller.ts
+```
+
+## CLI 参数
+
+| 参数 | 简写 | 说明 |
+|------|------|------|
+| `--module` | `-m` | 模块名（如 home/order/goods） |
+| `--table` | `-t` | 数据库表名（如 sys_dept/city/order_info） |
+| `--src` | `-s` | Midway src 根路径，默认 `./src` |
+| `--output` | `-o` | 生成文件输出路径，默认与 `--src` 相同 |
+| `--templates-path` | - | 自定义模板目录路径 |
+| `--force` | `-f` | 强制覆盖已存在的文件 |
+| `--dry-run` | `-n` | 模拟运行，不实际写入文件 |
+| `--compile` | `-c` | 生成后自动执行 `mwtsc --cleanOutDir` |
+| `--only-entity` | - | 仅生成 entity 文件，不生成 DTO/VO/Service/Controller |
+| `--no-db` | - | 不连接数据库，使用模板字段模式 |
+| `--db-host` | - | 数据库 host |
+| `--db-port` | - | 数据库端口，默认 3306 |
+| `--db-user` | - | 数据库用户名 |
+| `--db-pass` | - | 数据库密码 |
+| `--db-name` | - | 数据库名 |
+| `--help` | `-h` | 显示帮助信息 |
+
+## 配置文件
+
+在项目根目录或 `--src` 指向的目录下放置配置文件，支持以下格式（按优先级从高到低）：
+
+- `crud.config.ts`
+- `crud.config.js`
+- `crud.config.mjs`
+- `crud.config.cjs`
+- `.crudrc`
+- `.crudrc.json`
+- `.crudrc.yaml`
+- `.crudrc.yml`
+- `.crudrc.js`
+- `.config/crudrc`
+- `.config/crudrc.json`
+- `package.json` 中的 `"crud"` 字段
+
+### 配置示例（crud.config.ts）
+
+```typescript
+export default {
+  baseSrcPath: './src',
+  outputPath: './src',
+  moduleName: 'home',
+  tableName: 'sys_user',
+  force: false,
+  dryRun: false,
+  compile: false,
+  onlyEntity: false,
+  noDb: false,
+  templatesPath: './my-templates',
+  db: {
+    host: '127.0.0.1',
+    port: 3306,
+    user: 'root',
+    password: '',
+    database: 'mydb',
+  },
+};
+```
+
+### 配置字段说明
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `baseSrcPath` | `string` | `./src` | Midway 项目的 src 根目录绝对或相对路径。生成的模块文件将放在此目录下的 `modules/` 中。 |
+| `outputPath` | `string` | 与 `baseSrcPath` 相同 | 生成文件的输出路径。如需将代码生成到其他目录（如临时目录），可单独指定此项。 |
+| `moduleName` | `string` | 交互式询问 | 业务模块名，用于组织目录结构，如 `home`、`order`、`goods`。 |
+| `tableName` | `string` | 交互式询问 | 数据库表名，如 `sys_user`、`city`、`order_info`。用于生成类名和 DESCRIBE 表结构。 |
+| `force` | `boolean` | `false` | 是否强制覆盖已存在的文件。为 `false` 时遇到同名文件会跳过并提示。 |
+| `dryRun` | `boolean` | `false` | 模拟运行模式。只打印将要生成的文件列表，不实际写入磁盘。适合预览效果。 |
+| `compile` | `boolean` | `false` | 生成完成后是否自动执行 `mwtsc --cleanOutDir` 进行 TypeScript 编译。 |
+| `onlyEntity` | `boolean` | `false` | 仅生成 entity 实体文件，不生成 DTO、VO、Service、Controller 等其他文件。适合只需要实体类的场景。 |
+| `noDb` | `boolean` | `false` | 不连接数据库读取表结构。启用后使用内置模板字段生成（字段为示例占位，需手动修改）。 |
+| `templatesPath` | `string` | 无 | 自定义模板目录路径。在此目录下放置与默认模板同名的 `.njk` 文件即可覆盖对应模板。未覆盖的模板继续使用默认模板。 |
+| `db.host` | `string` | `127.0.0.1` | 数据库主机地址。 |
+| `db.port` | `number` | `3306` | 数据库端口。 |
+| `db.user` | `string` | `root` | 数据库用户名。 |
+| `db.password` | `string` | 空 | 数据库密码。 |
+| `db.database` | `string` | 交互式询问 | 数据库名。指定后会尝试连接数据库并 DESCRIBE 表结构，使用真实字段信息生成代码。 |
+| `db.type` | `string` | `mysql` | 数据库类型，目前仅支持 MySQL。 |
+
+> **优先级说明**：命令行参数 > 配置文件 > 默认值。例如命令行传了 `--force`，即使配置文件中 `force: false`，最终也会以 `true` 为准。
+
+## 自定义模板
+
+本工具使用 [nunjucks](https://mozilla.github.io/nunjucks/) 作为模板引擎。所有模板文件均可自定义。
+
+### 使用方式
+
+1. 将默认模板复制到项目目录（如 `./my-templates`）
+2. 修改模板内容
+3. 通过 `--templates-path ./my-templates` 参数或配置文件 `templatesPath` 指定自定义模板目录
+
+未覆盖的模板会自动使用默认模板。
+
+### 可用的模板文件
+
+| 模板名 | 文件名 | 说明 |
+|--------|--------|------|
+| entity | `entity.njk` | 实体类 |
+| dto-create | `dto-create.njk` | 创建 DTO |
+| dto-update | `dto-update.njk` | 更新 DTO |
+| dto-replace | `dto-replace.njk` | 替换 DTO |
+| dto-query | `dto-query.njk` | 查询 DTO |
+| dto-index | `dto-index.njk` | DTO 索引导出 |
+| vo-single | `vo-single.njk` | 单个 VO |
+| vo-list | `vo-list.njk` | 列表 VO |
+| vo-index | `vo-index.njk` | VO 索引导出 |
+| service | `service.njk` | Service 类 |
+| controller | `controller.njk` | Controller 类 |
+| crud-page-vo | `crud-page-vo.njk` | 分页 VO（全局共享） |
+
+### 模板变量参考
+
+#### entity.njk
+
+```
+orm: string              // ORM 类型：typeorm/sequelize/mikro-orm
+ormSuffix: string        // 实体文件后缀：entity/model
+fields: Array<{          // 字段列表（排除主键和基础字段）
+  name: string           // 数据库字段名
+  camel: string          // 驼峰命名
+  type: string           // 数据库类型
+  jsType: string         // JavaScript 类型
+  ormType: string        // ORM 类型
+  len: number | null     // 字段长度
+  nullable: boolean      // 是否可空
+  comment: string        // 字段注释
+  supportsLength: boolean
+  isDate: boolean
+  isSensitive: boolean
+  idx: boolean           // 是否索引字段
+}>
+tableName: string        // 表名
+Pascal: string           // PascalCase 命名
+Camel: string            // camelCase 命名
+pkInfo: Object | null    // 主键信息
+hasPk: boolean           // 是否有主键
+hasDateField: boolean    // 是否有日期字段
+idxCount: number         // 索引字段数量
+```
+
+#### dto-create.njk / dto-update.njk / dto-replace.njk
+
+```
+CreateName: string       // Create DTO 类名
+UpdateName: string       // Update DTO 类名
+ReplaceName: string      // Replace DTO 类名
+Pascal: string           // PascalCase 命名
+createFields: Array      // 可创建字段
+writable: Array          // 可写字段
+picks: string            // Pick 类型的字段列表字符串
+typeArgs: string         // 类型联合字符串
+```
+
+#### service.njk
+
+```
+ServiceName: string      // Service 类名
+Pascal: string           // PascalCase 命名
+Camel: string            // camelCase 命名
+ormInfo: {
+  orm: string
+  ormSuffix: string
+  serviceParent: string  // 父类名
+  importCrudOrm: string  // 导入语句
+  injectEntity: string   // 装饰器名
+}
+```
+
+#### controller.njk
+
+```
+CtrlName: string         // Controller 类名
+ServiceName: string      // Service 类名
+Pascal: string
+Camel: string
+pluralKebab: string      // 复数 kebab-case 路由名
+tagName: string          // Swagger tag 名
+desc: string             // 接口描述
+sortable: string[]       // 可排序字段
+filterable: string[]     // 可过滤字段
+searchable: string[]     // 可搜索字段
+```
+
+### 自定义模板示例
+
+在 `./my-templates/service.njk` 中：
+
+```njk
+import { Provide, Inject } from '@midwayjs/core';
+import { {{ Pascal }} } from '../entity/{{ Camel }}.entity';
+import { BaseService } from '../framework/base.service';
+
+@Provide()
+export class {{ ServiceName }} extends BaseService<{{ Pascal }}> {
+
+  entityClass = {{ Pascal }};
+
+  // 在这里添加你的自定义方法
+  async customMethod() {
+    // ...
+  }
+}
+```
+
+## 编程式 API
+
+除了 CLI，也可以在代码中直接调用：
+
+```typescript
+import { buildFiles, createRenderer, loadConfig } from '@shys/crud';
+import { writeFileSync } from 'node:fs';
+
+// 1. 使用 buildFiles
+const result = buildFiles({
+  moduleName: 'home',
+  tableName: 'sys_user',
+  baseSrcPath: './src',
+  ormInfo: { /* ... */ },
+  fields: [ /* ... */ ],
+  onlyEntity: false,
+});
+
+result.files.forEach((f) => {
+  writeFileSync(f.path, f.content);
+});
+
+// 2. 使用模板渲染器
+const renderer = createRenderer({
+  customTemplatesPath: './my-templates',
+});
+
+const code = renderer.render('entity', {
+  orm: 'typeorm',
+  fields: [ /* ... */ ],
+  Pascal: 'SysUser',
+  // ...
+});
+
+// 3. 加载配置文件
+const config = await loadConfig(process.cwd());
+```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shys/crud",
-  "version": "1.0.1-beta.0",
+  "version": "1.0.1-beta.2",
   "description": "MidwayJS v4 模块化 CRUD CLI 生成器",
   "license": "MIT",
   "author": {
@@ -14,7 +14,8 @@
   },
   "files": [
     "dist",
-    "templates"
+    "templates",
+    "README.md"
   ],
   "scripts": {
     "build": "tsc",

package/templates/entity.njk

@@ -6,7 +6,7 @@ import { Entity, Column{% if hasPk %}, PrimaryGeneratedColumn{% endif %}{% if id
 import { Expose{% if hasDateField %}, Transform{% endif %} } from 'class-transformer';
 import { ApiProperty, ApiPropertyOptional } from '@midwayjs/swagger';
 import { Rule } from '@midwayjs/validation';
-import { z } from 'zod';
+import * as Joi from 'joi';
 import { BaseEntity } from '../../../framework/entity/base.entity';
 
 @Entity({{ tableName | json }}, {
@@ -24,7 +24,7 @@ export class {{ Pascal }} extends BaseEntity {
     description: {{ (pkInfo.comment or '主键ID') | json }},
   })
   @Expose()
-  @Rule(z.number().int().describe({{ (pkInfo.comment or '主键ID') | json }}))
+  @Rule(Joi.number().integer().required())
   {{ pkInfo.camel }}: number;
 
 {% endif -%}
@@ -46,7 +46,7 @@ export class {{ Pascal }} extends BaseEntity {
 {% if f.defaultVal != null %}    example: {{ f.defaultVal | json }},
 {% endif %}  })
   @Expose()
-  @Rule({{ f.zodRule }}.nullable().optional())
+  @Rule({{ f.joiRule }})
 {% if f.isDate %}  @Transform(({ value }) => {
     if (value == null) return null;
     const d = value instanceof Date ? value : new Date(value);