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

package/README.md

@@ -0,0 +1,274 @@
+# @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
+```
+
+生成的目录结构：
+
+```
+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',
+  },
+};
+```
+
+## 自定义模板
+
+本工具使用 [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.1",
   "description": "MidwayJS v4 模块化 CRUD CLI 生成器",
   "license": "MIT",
   "author": {
@@ -14,7 +14,8 @@
   },
   "files": [
     "dist",
-    "templates"
+    "templates",
+    "README.md"
   ],
   "scripts": {
     "build": "tsc",