代码生成与领域特定语言

低代码的两种执行模式：
  解释执行：运行时读元数据 → 解释 → 渲染
    优点：改配置即时生效
    缺点：运行时开销、依赖平台

  生成执行：构建期元数据 → 生成代码 → 部署
    优点：性能好、可脱离平台、可人工维护
    缺点：有构建步骤、改动有延迟

成熟平台通常两者并存：
  内部使用 → 解释（快）
  对外交付/关键系统 → 生成（稳、可掌控）

逃生舱的三个层次：
  L1 导出元数据（JSON）
     最弱，只有平台能解释
  L2 导出配置 + 运行时（平台运行时开源/可部署）
     中等，脱离平台服务但依赖运行时
  L3 导出可独立运行的代码（框架无关或标准框架）
     最强，完全脱离平台

建议目标：至少 L2，关键场景 L3

模板式（Template-based）：
  用模板字符串 + 占位符生成文本
  优点：简单、上手快、适合代码结构固定的场景
  缺点：拼接易出错、难保证语法正确、重构难

AST 式（AST-based）：
  构造抽象语法树，再序列化为代码
  优点：语法保证正确、可格式化、可分析
  缺点：需要目标语言的 AST 库、实现复杂

// 模板式：简单直接，但需小心转义
function genEntityModel(entity: Entity): string {
  const fields = entity.fields
    .map((f) => `  ${f.name}: ${tsType(f.type)};`)
    .join('\n');
  return `export interface ${pascal(entity.name)} {\n${fields}\n}\n`;
}

// 输出
// export interface Order {
//   id: string;
//   amount: number;
// }

// AST 式：用 ts-morph 构造，天然保证语法正确
import { Project } from 'ts-morph';

function genInterface(entity: Entity) {
  const project = new Project();
  const file = project.createSourceFile('types.ts');
  file.addInterface({
    name: pascal(entity.name),
    properties: entity.fields.map((f) => ({
      name: f.name,
      type: tsType(f.type),
    })),
  });
  return file.getFullText();
}

好的 DSL 特征：
  1. 表达力刚好覆盖领域（不多不少）
  2. 可读性高（非专家也能看懂）
  3. 可校验（能静态检查）
  4. 可演化（向后兼容）
  5. 有边界（不图灵完备）

差的 DSL 特征：
  万能、什么都想表达 → 变成「用 JSON 写代码」

# 一个良好的流程 DSL 片段：语义清晰、可校验
flow: leave_approval
steps:
  - id: submit
    type: form
    form: leave_form
  - id: approve
    type: approval
    assignee: { role: manager }
    condition: "{{ days <= 3 }}"
  - id: hr_approve
    type: approval
    assignee: { role: hr }
    condition: "{{ days > 3 }}"

function tsType(t: FieldType): string {
  switch (t) {
    case 'string': case 'text': case 'date': case 'datetime':
    case 'enum': return 'string';
    case 'integer': case 'decimal': return 'number';
    case 'boolean': return 'boolean';
    case 'json': return 'unknown';
    case 'ref': return 'string';       // 存 id
    default: return 'unknown';
  }
}

可读性要点：
  1. 格式规范：生成的代码应通过 prettier/eslint
  2. 命名合理：用业务名而非 id
  3. 注释来源：把元数据里的 label/comment 变成注释
  4. 稳定排序：字段顺序稳定，避免无意义 diff
  5. 文件头：标注「自动生成，勿手改」

const HEADER = `/* eslint-disable */
// 此文件由低代码平台自动生成，请勿手动修改
// 生成时间: ${new Date().toISOString()}
// 来源: app_1024/order@v3
`;

三种策略：
  A. 生成物只读
     用户改生成物即失去平台同步，简单但僵硬
  B. 生成物可改，平台不覆盖已改文件
     用哈希检测手工修改，跳过这些文件
  C. 生成到独立文件，手写放另一文件
     生成基类/接口，手写实现继承/实现它
     推荐：最干净，往返安全

// 策略 C：生成基类，手写扩展
// 生成文件：order.generated.ts
export class OrderServiceBase {
  async findById(id: string) { /* 自动生成 */ }
}

// 手写文件：order.service.ts（平台不覆盖）
import { OrderServiceBase } from './order.generated';
export class OrderService extends OrderServiceBase {
  async findWithDiscount(id: string) {
    const o = await this.findById(id);
    return { ...o, discount: computeDiscount(o) };
  }
}

定位 A：一次性导出（快照）
  导出后与平台脱钩，后续在代码库独立演进
  适合：交付给客户、长期维护的系统

定位 B：持续同步（单向生成）
  平台是唯一真相，每次改动重新生成
  适合：平台内持续迭代的应用

混合：
  结构由平台生成（持续同步）
  业务逻辑手写（独立演进）

生成器质量保障：
  1. 幂等：相同输入产生相同输出（可 diff 校验）
  2. 可编译：生成物必须通过编译（CI 校验）
  3. 确定性：字段排序稳定、无随机/时间戳
  4. 快照测试：对生成结果做快照，变更需显式确认
  5. 往返测试：生成 → 解析 → 再生成，结果一致

// 幂等测试
test('generator is idempotent', () => {
  const a = generate(metadata);
  const b = generate(metadata);
  expect(a).toEqual(b);
});

场景 1：后端 CRUD
  元数据 → Controller/Service/Repository + 路由 + 校验
  收益：省去大量样板代码

场景 2：前端页面
  元数据 → 页面组件 + 表单 + 表格
  收益：把搭建结果变成可维护的前端代码

场景 3：类型定义
  元数据 → TypeScript 类型 + API 客户端
  收益：前后端类型一致，编译期发现不匹配

// 场景 3：生成类型安全的 API 客户端
function genApiClient(entities: Entity[]): string {
  return entities.map((e) => `
export const ${camel(e.name)}Api = {
  list: (params?: ListParams) => http.get<${pascal(e.name)}[]>('/${e.name}', { params }),
  get: (id: string) => http.get<${pascal(e.name)}>('/${e.name}/' + id),
  create: (data: Omit<${pascal(e.name)}, 'id'>) => http.post('/${e.name}', data),
};`).join('\n');
}