@pylonts/generator

从 DSL DTO schema 生成后端 CRUD 五层骨架（Entity / Convert / DAO / Service / Controller），并支持 HMAC 密钥签发链路、前端 API client、前端 API 调用文件的生成。

核心理念：骨架生成 + 增量合并。 生成器只负责结构与样板代码；业务逻辑（统计字段填充、业务校验）以 TODO(not_implement) 占位，由开发者实现。默认 append 模式——已存在的文件只合并缺失的方法/接口，不覆盖手写代码。

安装

npm install -D @pylonts/generator tsx

CLI 命令：pylon-generator。项目内使用：

// package.json
{
  "scripts": {
    "gen": "pylon-generator",
    "gen:key": "pylon-generator --key",
    "gen:client": "pylon-generator --client",
    "gen:api": "pylon-generator --api"
  }
}

快速开始

1. 写项目配置 pylon.config.ts

import type { GenConfig } from '@pylonts/generator';

export default {
  dtoDir: 'dto_schema',              // DSL schema 目录
  dtoPkg: '@mall/api-dto',           // api-dto 包名
  enums: [{ pkg: '@mall/enums', dir: 'enums/src' }],
  modules: {
    admin: { urlPrefix: 'api/admin', auth: 'admin' },
  },
  pages: [
    { module: 'admin', schema: 'bd', title: '客户档案' },
  ],
} satisfies GenConfig;

2. 生成

pylon-generator            # 生成 pylon.config.ts 中全部 pages
pylon-generator --module admin --schema bd   # 只生成指定页面
pylon-generator --dry-run  # 预演，不写文件
pylon-generator --overwrite # 覆盖整个文件（默认 append 合并）

3. 产物结构（模块目录 api/src/modules/{module}/）

controller/{Schema}Controller.ts  路由 + 参数校验 + 鉴权装饰器
service/{Schema}Service.ts        业务逻辑（统计字段 TODO 占位）
dao/{Schema}Dao.ts                knex 查询（列表过滤 / 分页 / 新增 / 更新 / 详情）
convert/{Schema}Convert.ts        Row → 列表行 转换（日期格式化）
entities/{Schema}Entity.ts        ListRow / StatsRow / InsertRow / UpdateRow 类型
route.config.ts                   urlPrefix + module（首次生成）

CLI 命令

pylon-generator [configPath] [--module M] [--schema S] [--all] [--overwrite] [--dry-run]
pylon-generator --key [--overwrite]
pylon-generator --client [--overwrite]
pylon-generator --api [--overwrite] [--module <name>]

| 命令 | 作用 | |---|---| | 默认（无子命令） | 从 pylon.config.ts 的 pages 生成 CRUD 五层 | | --key | 从 key.config.ts 生成 HMAC 密钥签发链路（key/issue + key/refresh） | | --client | 从 app.config.ts + key.config.ts 生成各前端应用的 API client | | --api | 扫描后端 controller，生成前端 API 调用文件 |

configPath 默认 ./pylon.config.ts。--module / --schema 过滤生成范围；--all 生成全部（默认）；--overwrite 覆盖已存在文件（默认 append 合并缺失内容）；--dry-run 只打印将执行的动作。

配置

GenConfig（pylon.config.ts）

| 字段 | 默认 | 说明 | |---|---|---| | root | '.' | 项目根目录（相对 process.cwd()） | | dtoDir | 'dto_schema' | DSL schema 目录 | | dtoPkg | — | api-dto 包名（必填） | | enums | [] | 枚举产物（包名 + 目录），用于解析 schema ENUM 列 | | naming | 见下 | DTO 命名约定（{Name} 替换为 PascalCase schema 名） | | backend | — | 后端接线：modulesDir / importPrefix / fastifyPkg / daoPkg / dateUtils / layers | | pages | [] | 实体级配置（批量生成入口） |

后端模块由 app.config.ts 的 app 列表 1:1 推导（一个 app 一个后端模块，目录名 = app 名）；不再需要模块映射表。

默认命名约定（naming）：

row:            '{Name}Row'
listRequest:    '{Name}PageRequest'   // 分页列表
listResponse:   '{Name}PageResponse'
detailRequest:  '{Name}DetailRequest'
detailResponse: '{Name}DetailResponse'
paginationBase: 'PageRequest'
listMethod:     'page'

backend 默认值：modulesDir: 'api/src/modules'、importPrefix: '@/'、fastifyPkg: '@pylonts/fastify'、daoPkg: '@pylonts/dao'。backend.dateUtils 配置后，Convert 层对日期字段调用指定格式化函数；backend.layers 可关闭某层（如 { controller: false } 跳过 controller 生成）。

PageConfig（pages 条目）

| 字段 | 说明 | |---|---| | module | 后端模块名（== dsl 子目录名） | | schema | dsl 文件名（不含 .dsl.dto.ts），如 bd | | title | 页面标题（中文） | | naming | 单页命名覆盖（偏离项目约定的 DSL 使用） | | operations | 自定义操作按钮 | | forms | add / update 表单配置（label / request DTO 名 / fields） | | detail | 详情模式（modal / route） | | keyword | 关键字模糊搜索：columns（LIKE 匹配的 DB 列） | | orderBy | 列表排序：column + direction（默认 desc） | | auth | Controller 鉴权：'login'（默认）或 'public' |

key.config.ts（--key 使用）

export default { store: 'db', module: 'common' };

• store: 'db' → 生成 schema 表 + dsl-dto + entity/dao/service/controller + config resolver
• store: 'redis' → 生成 dsl-dto + service（RedisKeyStore）+ controller + config resolver

app.config.ts（--client / --api 使用）

export const contextPath = '/mall';
export const apps = [
  { name: 'admin', type: 'admin' },
  { name: 'miniuser', type: 'wx' },
];

--client 按 app 类型生成 src/api/client.ts：admin 用 @pylonts/api-client（fetch + localStorage + antd message），wx 用 @pylonts/api-client-wx（wx.request + wx storage）。目录约定同 pylon-init：admin → {name}-admin，wx → {name}。

生成策略

| 模式 | 行为 | |---|---| | 默认（append） | 已存在文件只合并缺失的方法/接口与 import，保留手写代码 | | --overwrite | 整个文件重新生成 | | --dry-run | 打印 CREATE / OVERWRITE / SKIP / MERGE 标签，不写文件 |

不支持的 DTO 形状（非分页列表、单对象请求等）会报告并跳过。

相关包

• @pylonts/dsl-dto — DSL DTO 定义（schema 解析的源头）
• @pylonts/schema-core / @pylonts/mysql-schema — 表定义与 MySQL 类型映射
• @pylonts/fastify / @pylonts/dao — 生成的 controller / dao 依赖的运行时包
• @pylonts/api-client / @pylonts/api-client-wx — --client 生成的前端 client 运行时包