代码生成方法论

这份规则描述的是模型在实际生成代码时所遵循的真实决策过程。它覆盖从读取现有代码到输出新代码的完整链路，包括模式识别机制、一致性维护规则、以及多文件改动的顺序控制。理解并遵循这些规则是保证生成代码能够无缝融入现有代码库的基础。

一、写代码之前：读懂现有模式

1.1 模式优先于知识

模型拥有大量关于各种编程语言、框架和设计模式的通用知识。但在一个具体的代码库中，这些通用知识必须让位于代码库已经建立的具体模式。

原因是：每个代码库都是在通用知识的基础上做了大量具体选择的结果，这些选择包括命名风格、目录结构、错误处理方式、日志格式、数据访问方式、组件通信方式等。如果模型用通用知识覆盖代码库的具体选择，产出的代码会在风格上与已有代码格格不入，增加维护成本。

flowchart TD
    A[接收代码生成任务] --> B[识别相关的现有代码]
    B --> C[提取已有模式]
    C --> C1[命名约定]
    C --> C2[文件和目录结构]
    C --> C3[错误处理方式]
    C --> C4[数据访问模式]
    C --> C5[导入和依赖组织方式]
    C1 & C2 & C3 & C4 & C5 --> D[建立代码库模式模型]
    D --> E[在模式约束下生成新代码]

1.2 需要读取的内容

在生成新代码之前，需要阅读以下内容：

与任务直接相关的现有文件，理解它的结构、依赖和模式。同类型的其他文件（比如如果要写一个新的 API 控制器，读一个已有的控制器），理解这个类型的文件在这个代码库里是怎么写的。被新代码依赖的文件（工具函数、基础类、配置等），理解它们的接口和使用方式。会依赖新代码的文件（如果能确定的话），理解它们期望的接口形式。

1.3 读代码时需要提取的信息

读现有代码不是简单地浏览，而是主动提取以下信息：

函数和变量的命名模式（驼峰还是下划线，动词在前还是名词在前，缩写还是全拼）。错误处理的统一方式（抛出异常还是返回错误对象，错误日志的格式，用户可见的错误消息的形式）。异步处理的方式（async/await 还是 Promise 链，回调还是 Observable）。数据获取和状态更新的模式（在哪里发请求，数据如何在组件或模块间传递）。测试的覆盖方式（有没有测试，测试文件在哪里，测试的粒度是什么）。

二、生成代码的核心原则

2.1 最小改动原则

每次代码改动应该只包含为了完成任务必须做的最小集合。不要在完成任务的同时顺手重构代码，不要改变与任务无关的格式或命名，不要删除看起来没用但没有完全确认的代码。

这个原则的理由是：每一行额外的改动都是引入新 Bug 的机会，都是在代码审查中需要额外解释的内容，都是版本历史中的噪声。如果发现了需要重构的问题，单独提出来而不是顺手做掉。

flowchart TD
    A[需要实现某个功能] --> B[确定最小的实现集合]
    B --> C{是否发现了可以顺手改进的地方}
    C -- 是 --> D[记录下来单独处理]
    C -- 否 --> E[只做最小集合的改动]
    D --> E
    E --> F[验证改动完成了任务]
    F --> G[检查改动是否引入了意外的副作用]

2.2 一致性维护

新生成的代码必须在多个维度上与现有代码保持一致：

风格一致性：缩进、括号位置、引号类型、分号有无，完全遵循现有代码的风格，不使用个人偏好。

命名一致性：在同一个代码库中，相同类型的事物应该有相同格式的名称。如果现有的 HTTP 处理函数都叫 handleXxx，新的处理函数也应该叫 handleXxx 而不是 onXxx 或 xxxHandler。

结构一致性：文件的组织方式（导入的顺序、函数的排列方式、类成员的顺序）应该与同类文件保持一致。

错误处理一致性：如果代码库中所有的异步操作都使用 try-catch，新代码也应该使用 try-catch，不应该引入链式 .catch() 的写法。

2.3 防御性编程的默认立场

对所有来自外部的输入持怀疑态度。函数的参数可能是 null，API 的响应可能缺少字段，数据库的查询结果可能是空的，用户的输入可能包含恶意内容。

防御性编程不是到处加检查，而是在数据进入系统的边界处做一次完整的校验，确保进入系统内部的数据是已知格式的。边界之内的数据可以信任，边界之外的数据不能信任。

flowchart LR
    subgraph 外部世界
        A[用户输入]
        B[API 响应]
        C[数据库结果]
        D[文件读取]
    end
    subgraph 边界层
        E[输入验证\n类型检查\n格式规范化]
    end
    subgraph 系统内部
        F[业务逻辑\n可以信任数据格式]
    end
    A & B & C & D --> E --> F

三、多文件改动的顺序控制

3.1 依赖关系决定改动顺序

当一个任务需要修改多个文件时，改动的顺序必须遵循依赖关系：被依赖的文件先改，依赖它的文件后改。

原因是：如果先改了调用方的代码，而被调用方的接口还没有更新，中间状态的代码是不可编译或不可运行的，这会给调试带来困难，也会让审查代码的人产生困惑。

flowchart TD
    A[确定需要修改的文件集合] --> B[分析文件之间的依赖关系]
    B --> C[确定拓扑排序的改动顺序]
    C --> D[从被依赖的底层文件开始改动]
    D --> E[逐步向上改动依赖它的文件]
    E --> F[最后改动最顶层的入口文件]
    F --> G[整体验证所有改动的一致性]

3.2 接口先于实现

当需要新增一个模块或服务时，先定义它的接口（类型定义、函数签名、API 协议），再实现细节。这样做的好处是：接口确定之后，调用方和被调用方可以独立开发；接口是系统边界的文档，先定义接口有助于发现设计问题，比在实现完成之后再发现设计有问题的修复成本低得多。

3.3 改动的原子性

每一次完整的改动应该是原子的，即所有相关的文件都被改动到一个一致的状态，不应该存在"部分完成"的改动状态。如果一个任务需要同步修改多个文件，这多个文件的改动必须都完成，才能说这个任务完成了。

四、代码质量的真实判断标准

4.1 可读性是第一优先级

代码是写给人看的，其次才是写给机器执行的。一段可读性差但功能正确的代码，在需要修改时会带来远超其价值的维护成本。

可读性的核心是命名质量。一个好的名称应该：准确描述这个东西是什么或做什么，在它出现的上下文中不产生歧义，与代码库中相同类型的其他名称保持一致的格式。

一个不好的名称有以下特征：只描述类型而不描述含义（str、num、obj）、使用无意义的缩写（tmp、x、data）、描述的是实现细节而不是业务含义。

4.2 函数的单一职责

一个函数只做一件事，这件事应该能被函数的名称完整描述。如果一个函数名称中包含"and"，或者函数体超过一个屏幕，或者这个函数需要一段注释来解释它做什么，这些都是函数职责不清晰的信号。

单一职责的实际判断标准：如果需要修改这个函数，改动的原因有且只有一个。如果有多个不同性质的原因会导致这个函数需要修改，它就承担了多个职责。

4.3 显式优于隐式

代码的行为应该能从它的文字描述中直接读出，而不应该依赖对隐式规则、约定或副作用的了解。

隐式的例子：一个函数名叫 getUser 但同时修改了全局状态；一个参数传 true 表示升序、传 false 表示降序（这需要调用方记住这个约定）；一个变量的含义依赖于它在特定上下文中才能理解的隐式假设。

显式的替代：函数只做名称描述的事情；使用有意义的枚举值而不是布尔值；变量名包含足够的信息使得含义自明。

4.4 错误处理的完整性

每一个可能产生错误的操作都需要明确的错误处理。明确意味着：知道这个操作可能失败，决定了在失败时应该做什么（恢复、重试、向上传递、记录日志、通知用户），并且用代码实现了这个决定。

错误处理不完整的最常见表现：吞掉异常（catch 块里只有空行）、只在成功路径上有完整的逻辑而失败路径的处理是临时补上的、错误消息没有足够的上下文信息。

flowchart TD
    A[识别可能失败的操作] --> B{失败能否在当前层处理}
    B -- 能 --> C{处理方式}
    C -- 可以恢复 --> D[实现恢复逻辑\n继续正常流程]
    C -- 需要重试 --> E[实现重试逻辑\n含退避策略]
    C -- 需要降级 --> F[实现降级逻辑\n返回安全的默认值]
    B -- 不能 --> G[向上层传递\n附带足够的上下文信息]
    D & E & F & G --> H[记录日志\n包含足够的调试信息]

五、生成代码后的自我验证

5.1 功能正确性验证

生成的代码是否实现了任务要求的功能。走一遍主要的执行路径，确认逻辑是正确的。走一遍边界情况和错误情况，确认这些情况都有处理。

5.2 与现有代码的兼容性验证

新代码引入的依赖是否已经在代码库中可用。新代码使用的接口是否与它依赖的模块的实际接口一致。新代码的接口是否与依赖它的模块的期望一致。

5.3 副作用检查

改动是否在预期之外影响了其他功能。修改了共享的工具函数或基础类时，所有调用方是否都能正确处理新的行为。修改了数据结构时，所有使用该数据结构的地方是否都做了相应的更新。

flowchart TD
    A[代码生成完成] --> B[功能正确性验证\n主路径和边界情况]
    B --> C[兼容性验证\n接口一致性检查]
    C --> D[副作用检查\n共享代码的影响范围]
    D --> E{是否发现问题}
    E -- 是 --> F[定位问题根因]
    F --> G[修复问题]
    G --> B
    E -- 否 --> H[代码生成完成]