用生成器守住架构，用 AI 放大效率：一套可落地的 AI 编程方法论

背景与问题

现实困境 : 直接让 AI 产出整块业务代码，常常与现有架构风格、分层边界、依赖策略不一致，后续改造成本高；AI 对现实业务语境、领域规则难以精准把握；在既定模板成熟的场景下，代码生成器往往更快、更整齐。
目标: 保持团队既有架构与工程纪律，发挥 AI 在探索、补全、评审与加速学习上的优势，降低全周期交付成本。

总体策略：生成器为主干，AI 为增幅器

生成器（Generator）作为主干：强约束地输出骨架与重复性代码，以模块/分层/命名/依赖为"轨道"。
AI 作为增幅器：在"轨道"内进行探索、补全、评审、重构建议与知识蒸馏，避免直接替代主干生成。二者配合，形成"结构确定 + 局部智能"的稳态生产模式。

角色分工（清晰边界）

生成器职责
- 从 DSL/模型/配置生成项目骨架、实体、DAO、API 契约、DTO、基础 Service/Controller、前端表单/列表。
- 严格收敛目录与层次：如 JPA 实体统一落在资源层模块，按包约定与模板产出；控制器、开放接口放在 API/Gateway 层；公共库与工具类落在基础模块。
- 以模板升级推动"规范沉淀"，一处改进，全局受益。
AI 职责
- 需求梳理、用例设计、边界场景补全与反例思考。
- 局部函数实现（小而清晰的单点逻辑）、性能调优建议、异常与重试策略建议。
- 单元/集成/契约测试补全，变更影响面分析与回归清单建议。
- 代码评审（可读性、复杂度、耦合度、异常路径）、重构方案与风险提示。
- 文档沉淀（ADR、模块说明、限界上下文说明、时序/状态机/ER 草图）。
人类职责
- 领域建模与 DSL 维护、架构准入与裁剪、业务裁决与优先级、最后的合并把关。

标准工作流（从需求到上线）

以 DSL/配置（如 YAML）描述领域概念、对象关系、接口契约与约束。
通过代码生成器生成骨架与重复代码（遵循模块与分层约定）。
针对"不可模板化"的边缘逻辑，由 AI 在约束内补全实现（仅限局部函数/方法）。
让 AI 生成/补全单测与契约测试，并给出覆盖关键路径的回归清单。
运行构建与测试（本地/CI），失败用 AI 协助定位与修复，但仍遵守"只改动最小单元"的原则。
AI 生成变更摘要与自检清单（架构一致性、依赖边界、复杂度、日志、安全、i18n）。
人工审核后合并；将本次经验沉淀为模板升级与 Prompt 库更新。

守护栏（约束协议）

分层边界：禁止跨层调用与反向依赖；仓储只暴露接口、应用层不直连 ORM；控制器不写领域规则。
目录约束：实体/DTO/VO/Controller/Service/Repo/Config 各就其位，禁止"即兴"新建架构层级。
依赖策略：默认不引入新依赖；如确需新增，必须声明理由、对比与回滚方案。
复杂度阈值：函数圈复杂度、嵌套层级与参数个数设上限；超限需拆分并写测试。
风格一致性：日志、异常、国际化、命名、注释风格对齐基线；变更不重排无关格式。

Prompt 模板库（可直接复制使用）

A. 架构对齐开发（在现有模块内补全）

text 复制代码

你现在在现有代码库内进行"最小化改动"的代码补全，请严格遵守：
- 只在我点名的文件与函数内编辑；禁止新建层/模块；禁止引入新依赖。
- 分层与目录约束：
  - JPA 实体只在资源层的实体模块内；
  - Controller 仅放在 API 层；
  - Service 只编排应用逻辑，不写 SQL；
  - Repository 只定义数据访问接口。
- 输出内容包含：
  1) 你将修改的文件清单
  2) 具体改动（只给出必要片段）
  3) 架构一致性自检（逐条对照约束）
  4) 回归测试建议（列关键路径与断言）

现在任务：在 {文件路径}:{函数名} 中实现 {功能要点}，要求 O(变更最小)。
给出实现方案与测试要点。

B. 领域建模与 DSL 同步

text 复制代码

基于以下业务描述，产出领域对象、关系、约束与状态流转；并给出可合并到生成器的 DSL/YAML 片段：

业务描述：{贴上需求/规则/票据}

输出：
- 实体清单（名词 + 关键字段 + 关系）
- 约束（唯一性、枚举、状态机、生命周期）
- API 契约草案（接口名、入参、出参、错误码）
- 生成器 DSL/YAML（仅新增或变更的条目）
- 风险与歧义清单（等待澄清的问题）

C. 边缘逻辑最小实现

text 复制代码

请仅在 {文件路径}:{函数名} 内实现以下逻辑：{逻辑描述}。
约束：
- 不改其他函数，不新增依赖，不改变公共接口签名。
- 控制复杂度：最多两层分支，必要时早返回；为空/异常/边界优先处理。
- 提供 3 个单元测试用例，覆盖正常、边界、异常路径。
- 产出"自检清单"（日志、异常、并发、性能要点）。

D. 代码评审与重构建议

text 复制代码

下面是本次变更的 diff（或关键文件片段）。请按以下维度给出审查结论与可执行的最小重构建议：
- 架构与分层一致性
- 可读性与命名
- 复杂度与边界处理
- 性能与资源释放
- 日志、异常与可观测性
- 安全与多租户/权限

输出：
1) 问题列表（按严重级别排序）
2) 可直接粘贴的最小重构代码片段
3) 回归风险与测试建议

E. 故障定位与修复

text 复制代码

给定以下错误堆栈/日志/SQL，请在不新增依赖的前提下，给出最小修复方案：
- 根因分析（链路 + 证据）
- 修复思路（最小改动）
- 具体修改片段（限定在 {文件路径}）
- 回归测试与监控点

F. 文档沉淀（ADR/模块说明）

text 复制代码

请根据这次需求与变更，产出一份 ADR：
- 背景与动机
- 备选方案对比（取舍理由）
- 决策与影响面
- 迁移/回滚策略
- 后续工作与度量指标

与代码生成器的协同

模板为王：将通用实践推进到模板（如 Controller/Service/Repo/DTO/前端 CRUD 模板）。模板升级即团队升级。
DSL 收敛：统一在一处维护领域词汇表、对象属性与 API 契约；AI 输出的 DSL 片段经人审后并入生成器配置。
Schema-first：优先以 OpenAPI/AsyncAPI/Avro 等契约驱动，生成器产出骨架，AI 生成契约测试与示例。

减少偏差的具体做法

小步提交：AI 只处理一个函数或一个文件的局部，配套 2-3 个用例。
显式拒绝：当请求超出约束（跨层、添依赖、大改签名），AI 应先拒绝并给出替代路径。
回归快跑：保存一组"金样本"用例，AI 修改后先本地跑，CI 再跑；覆盖率门槛可由 AI 给出补测建议。
固定示例：给 AI 提供项目内"代表性样例文件"，作为风格与边界的锚点。

现实业务知识的注入

语义注入：把内部术语表、状态机、时序图、规则表放入上下文；要求 AI 在输出前列出"未知项"和"假设"。
上下文包：为 AI 预打包"架构约束 + 目录约定 + 命名规范 + DSL 摘要"，作为每次对话的前置输入。

在你项目中的落地清单（可执行）

目录与分层：固化"实体/DAO/Service/Controller/DTO/VO/前端页面"的落位规则；以 pre-commit 检查违规路径。
模板沉淀：把常见的查询、分页、审计字段、软删除、异常处理、日志切面、统一响应，写进生成器模板。
Prompt 库 ：将上文模板存入 documents/ai/prompt/，按业务域分目录；每次评审后更新。
PR 模板：新增 PR 模板，强制"架构一致性自检 + 回归清单 + 监控点"。
CI 守护：风格检查 + 单测 + 契约测试 + 违规路径扫描（例如禁止实体出现在错误模块）。

结论

最优解不是"全靠 AI"或"完全不用 AI"，而是"生成器守住工程与架构的秩序，AI 放大探索、补全与评审的效率"。
以"强约束 + 小步快跑 + 模板沉淀 + 语义注入"的方法，能把 AI 变成可控、可度量的生产力，而非一次性的"灵感"。

附：最小可行用法（15 分钟上手）

用生成器产出实体/DAO/Service/Controller 骨架。
让 AI 只在某个 Service 的"单个函数"里补齐特定业务逻辑。
让 AI 写 3 个单测用例，覆盖正常/边界/异常；本地跑通。
让 AI 给出自检清单与回归建议；人工核查后合并。

面向 nb-mall 的项目结构对齐（定制落地指南）

模块职责与产出路径映射

resources/business-resource （领域资源层）
- 放置 JPA 实体、Repository 接口、领域枚举与基础转换器。
- 注意：依据你的偏好，JPA 实体应统一放在该模块下，避免分散在其他模块[[memory:3731451]]。
apis/business-api （开放接口层）
- 放置对外 REST Controller、DTO/VO、入参校验对象与装配器（Assembler/Converter）。
- 不直接访问 ORM，依赖应用服务抽象或 Facade。
gates/admin （网关/聚合层）
- 统一鉴权、路由转发、跨域与限流等横切能力；避免业务逻辑侵入。
code-generator （模板与 DSL）
- src/main/resources/config/*.yml 维护领域 DSL；template/jpa/*.ftl、template/vue/*.ftl 产出后端与前端骨架。
front/ （多端前端）
- admin/：后台运营端（Vue）。
- pos/：门店/收银端（Vue）。
- front/：C 端站点（Nuxt）。
- uniapp/：移动端（uni-app）。

建议的代码生成落位规则

实体与 Repository → resources/business-resource
Controller/DTO/VO/Converter → apis/business-api
前端 CRUD 页面与表单 → front/admin（如为运营端）
若为 POS/移动端需求 → 同步生成到 front/pos 或 front/uniapp

标准开发流（结合现有结构）

在 code-generator/resources/config/*.yml 中完善 DSL（实体、字段、约束、接口契约、前端元数据）。
运行生成器产出骨架：
- 后端：实体/Repository → business-resource；Controller/DTO → business-api。
- 前端：列表/表单/路由 → front/admin（或目标端）。
对"不可模板化"的业务细节：仅在指定 Service 或函数中做最小改动；禁止跨层访问与新增依赖。
让 AI 生成/补全对应单元测试与契约测试（针对 business-api 的接口）。
本地与 CI 运行构建、测试；失败时用 AI 辅助定位，但只做最小修改。
评审时按"守护栏"逐条自检；将共性的改进沉淀回 code-generator 模板与 DSL。

与生成器的联动建议（nb-mall 实践）

在模板固化以下约定：
- 审计字段（创建/修改人与时间、租户/组织、软删除）。
- 统一返回体、异常编码、分页与排序约束、统一日志与拦截器。
- DTO/VO 命名规则与转换器（如 MapStruct 或手写装配器）。
在 DSL 文件加入前端元数据：
- 字段显示名、校验规则、枚举映射、字典/级联选择、搜索条件、列宽与排序。
- 由此驱动 front/admin 自动生成表单/列表/路由与权限点。

针对各端的差异化指引

front/admin：偏 CRUD + 运营工作台。优先使用生成器产出页面骨架与表单校验。
front/pos：交互流程固定、离线/并发要求更高。生成器负责骨架，AI 辅助补全缓存/并发边界与设备适配细节。
front/uniapp：注意端能力差异与网络状态波动。生成器产出页面与接口封装，AI 补充状态管理与降级策略。
front/front (Nuxt)：静态化与 SEO 需求更强。生成器产出基础页面/路由，AI 补全数据获取策略与性能细节（预取/缓存）。

nb-mall 定制 Prompt 模板（可直接复制）

【后端-对齐补全】

text 复制代码

只在以下边界内补全代码：
- 实体/Repository：resources/business-resource
- Controller/DTO/VO/Converter：apis/business-api
- 禁止新增依赖与跨层访问；不改变公共接口签名。

任务：在 {文件路径}:{函数名} 内实现 {功能要点}，给出：
1) 最小实现代码片段
2) 架构一致性自检（分层/依赖/异常/日志）
3) 3 个用例（正常/边界/异常），标注断言点

【前端-页面骨架增强】

text 复制代码

基于生成器已产出的页面骨架（位于 front/admin 或目标端），
请在不引入新依赖前提下补全：
- 表单校验、字典/枚举映射、搜索条件组合、分页与排序
- 交互细节：提交/并发/错误提示/重试
- E2E 场景清单与关键断言

【DSL 协同】

text 复制代码

根据以下业务描述，补充 code-generator/resources/config 的 DSL 片段：
- 实体与字段（含约束/索引/默认值/枚举）
- API 契约（入参/出参/错误码）
- 前端元数据（表单项、校验、字典、搜索项、列配置）
并指出歧义点与待澄清问题。

CI/CD 与守护脚本建议

在 PR 检查中加入"路径守护"：禁止实体/Repository 出现在非 business-resource 模块，禁止 Controller 出现在非 business-api。
启用契约测试（OpenAPI 校验）与接口变更告警。
前端构建加入路由/权限点扫描与 i18n 缺失校验。

15 分钟落地（nb-mall 版）

在 code-generator/resources/config/*.yml 新增/修改领域 DSL。
生成代码：后端落位到 business-resource 与 business-api，前端落位到 front/admin。
仅在目标函数中做最小实现；用 AI 生成 3 个用例并本地跑通。
提交 PR，走"路径守护 + 单测 + 契约测试"检查；评审后合并，并把共性补充回模板与 DSL。