@chongyan/autospec 1.0.2 → 1.0.3

package/knowledge/07-standards/00-coding-style.md

@@ -1,1059 +0,0 @@
-# 通用编码规范
-
-> **版本**: v1.1
-> **最后更新**: 2026-03-27
-> **适用范围**: 所有 Java/后端项目
-> **设计原则**: 安全第一、可读性优先、预防为主、复用优先
-
----
-
-## 📑 目录
-
-0. [复用优先与禁止硬编码](#0-复用优先与禁止硬编码)
-1. [数据安全](#1-数据安全)
-2. [异常处理](#2-异常处理)
-3. [多线程](#3-多线程)
-4. [数据库](#4-数据库)
-5. [国际化](#5-国际化)
-6. [安全](#6-安全)
-7. [日志打印](#7-日志打印)
-8. [监控规范](#8-监控规范)
-9. [编码基础](#9-编码基础)
-10. [命名规范](#10-命名规范)
-11. [面向对象设计原则](#11-面向对象设计原则)
-
----
-
-## 0. 复用优先与禁止硬编码
-
-### 0.1 优先复用项目现有能力
-
-**说明**: 在实现任何功能或修复问题时，必须先扫描项目已有的框架、工具类、组件。
-
-**强制要求**:
-- 实现前先搜索代码库，查找是否有类似实现
-- 优先使用项目已有的 AOP 框架、Helper 工具、Util 类
-- 按已有代码的模式和风格实现新功能
-- 绝不重复造轮子
-
-**错误示例**:
-```java
-// ❌ 项目已有 TracingHelper，却自己新建埋点类
-public class MyTracingHelper {
-    // 重复实现埋点逻辑
-}
-
-// ❌ 项目已有 LogUtil，却直接使用 logger
-private static final Logger logger = LoggerFactory.getLogger(Xxx.class);
-logger.info("xxx");  // 没有 TraceId，无法链路追踪
-```
-
-**正确示例**:
-```java
-// ✅ 复用项目已有的 TracingHelper
-@Autowired
-private TracingHelper tracingHelper;
-
-// ✅ 使用项目已有的 LogUtil（带 TraceId）
-LogUtil.info("key", "value");
-```
-
-### 0.2 禁止硬编码
-
-**说明**: 不可在代码中硬编码目录名、包名、类名、配置项等。
-
-**强制要求**:
-- 路径配置从配置文件或环境知识中读取
-- 技术栈信息从项目文件中动态识别
-- 支持不同项目的差异化配置
-
-**错误示例**:
-```java
-// ❌ 硬编码路径
-String configPath = "/home/user/projects/myapp/config/";
-
-// ❌ 硬编码包名
-String basePackage = "com.example.myapp.service";
-
-// ❌ 硬编码文件名
-String pomFile = "backend/service/pom.xml";
-```
-
-**正确示例**:
-```java
-// ✅ 从配置文件读取
-@Value("${app.config.path}")
-private String configPath;
-
-// ✅ 动态扫描识别
-File projectRoot = findProjectRoot();
-List<String> pomFiles = scanForPattern(projectRoot, "**/pom.xml");
-```
-
-### 0.3 设计原则约束
-
-自主修复场景下，必须遵循以下面向对象设计原则：
-
-**单一职责原则 (SRP)**:
-- 每个类/方法只负责一项职责
-- 修复代码不创建"上帝类"或"万能方法"
-- 职责单一便于维护、测试和复用
-
-**开闭原则 (OCP)**:
-- 对扩展开放，对修改关闭
-- 新增功能通过扩展实现，不修改已有核心代码
-- 通过接口或抽象类约束扩展边界
-
-**里氏替换原则 (LSP)**:
-- 子类必须能够替换其父类，程序行为不变
-- 继承必须确保合理，不破坏继承体系
-- 避免滥用继承，优先考虑组合
-
-**依赖倒置原则 (DIP)**:
-- 面向接口编程，不依赖具体实现
-- 高层模块和低层模块都依赖抽象
-- 通过构造函数注入、setter 注入实现依赖注入
-
-**接口隔离原则 (ISP)**:
-- 使用多个专门的接口，不使用单一的总接口
-- 将臃肿庞大的接口分解为多个独立的较小接口
-- 客户端不应该依赖它不需要的接口
-
-**迪米特法则 (最少知道原则)**:
-- 一个对象应该对其他对象有最少的了解
-- 只与直接的朋友通信，不与"陌生人"交谈
-- 降低类与类之间的耦合
-
-**合成/复用原则**:
-- 优先使用组合/聚合，其次才是继承
-- 组合复用比继承复用更灵活，耦合度更低
-
-**高内聚低耦合**:
-- 模块内部元素应紧密相关（高内聚）
-- 模块之间依赖应尽可能少（低耦合）
-- 变化点必须封装隔离（面向变化设计）
-
-**AOP 优先**:
-- 涉及跨切面功能（日志、埋点、鉴权、事务等）时，优先使用 AOP 切面方式
-- 禁止侵入业务代码，通过切面增强实现
-- 保持核心业务逻辑的纯净性
-
-> 详细说明和代码示例见：[第 11 节 面向对象设计原则](#11-面向对象设计原则)
-
----
-
-## 1. 数据安全
-
-### 1.1 更新数据前必须加锁（一锁二判三更新）
-
-**说明**: 在并发场景下，线程读取的数据可能已被其他线程篡改，导致状态机推进错误或重复操作。
-
-**原则**:
-- **一锁**: 锁定单点资源（单条记录），并发请求串行处理
-- **二判**: 基于锁定的记录最新状态，判断状态、数值
-- **三更新**: 判断通过后的处理
-
-**错误示例**:
-```java
-// ❌ 没有执行二判，直接更新
-transactionTemplate.execute((TransactionStatus status) -> {
-    record = repository.loadWithLock(recordId);
-    repository.update(record);  // 缺少状态检查
-    return true;
-});
-```
-
-**正确示例**:
-```java
-// ✅ 严格遵循一锁二判三更新
-transactionTemplate.execute((TransactionStatus status) -> {
-    // 1. 锁定记录
-    record = repository.loadWithLock(recordId);
-    // 2. 状态检查
-    record.validateState();
-    // 3. 更新
-    repository.update(record);
-    return true;
-});
-```
-
-### 1.2 禁止使用不安全的数值计算方法
-
-**说明**: float/double 是浮点数，会损失精度，严禁用于精度敏感的计算（金额、数量等）。
-
-**错误示例**:
-```java
-// ❌ 使用 double 进行精度敏感计算，可能导致精度丢失
-double value1 = 100.50;
-double value2 = 200.75;
-double total = value1 + value2;
-```
-
-**正确示例**:
-```java
-// ✅ 使用专用精度类型（推荐）
-import com.example.common.util.Decimal;
-
-Decimal value1 = new Decimal(100.50);
-Decimal value2 = new Decimal(200.75);
-Decimal total = value1.add(value2);
-```
-
-```java
-// ✅ 或使用 BigDecimal（多币种/高精度场景）
-import java.math.BigDecimal;
-
-BigDecimal value1 = new BigDecimal("100.50");
-BigDecimal value2 = new BigDecimal("200.75");
-BigDecimal total = value1.add(value2);
-```
-
----
-
-## 2. 异常处理
-
-### 2.1 必须在异步方法中捕获和处理异常
-
-**说明**: 使用 `@Async`、线程池、Future 等异步机制时，如果没有捕获异常，异常将不会被抛出，上层方法无感知。
-
-**错误示例**:
-```java
-// ❌ 异步方法中没有捕获和处理异常
-@Async
-public void asyncCheckStatus(List<String> items) {
-    for (String item : items) {
-        // do something - 如果抛异常，上层无感知
-    }
-}
-```
-
-**正确示例**:
-
-方式 1：显式捕获异常
-```java
-// ✅ 增加 try catch 显式地捕获和处理异常
-@Async
-public void asyncCheckStatus(List<String> items) {
-    try {
-        for (String item : items) {
-            // do something
-        }
-    } catch (Exception e) {
-        LogUtil.error(e, LOGGER, "异步处理发生异常，items={0}", items);
-        // 根据情况进行处理
-    }
-}
-```
-
-方式 2：使用带返回值的 AsyncResult
-```java
-// ✅ 使用 AsyncResult，上层通过 get() 捕获异常
-@Async
-public AsyncResult<String> asyncCheckStatus(List<String> items) {
-    for (String item : items) {
-        // do something
-    }
-    return new AsyncResult("success");
-}
-
-// 调用方
-public void test() {
-    try {
-        Future future = asyncCheckStatus();
-        future.get();  // 异常会在这里抛出
-    } catch (Exception e) {
-        LogUtil.error(e, LOGGER, "异步处理发生异常");
-    }
-}
-```
-
-### 2.2 必须处理被捕获的异常
-
-**说明**: 禁止使用空的 catch 语句块。忽略异常可能吞掉应该被处理或报告的异常，造成系统风险。
-
-**错误示例**:
-```java
-// ❌ 空的 catch 语句块
-public void bad() {
-    try {
-        // 可能抛出异常的代码
-    } catch (SpecificException e) {
-        // 空实现 - 吞掉异常，非常危险！
-    }
-}
-```
-
-**正确示例**:
-```java
-// ✅ 记录异常信息，并采取适当措施
-public void good() {
-    try {
-        // 可能抛出异常的代码
-    } catch (SpecificException e) {
-        LogUtil.error(e, LOGGER, "处理过程中发生异常");
-        // 提示用户或采取补救措施
-        notifyUser("发生错误，请重试");
-    }
-}
-```
-
----
-
-## 3. 多线程
-
-### 3.1 必须及时清理 ThreadLocal
-
-**说明**: ThreadLocal 使用完毕后不移除，会导致：
-- 线程复用时数据污染，影响业务正确性
-- 内存泄漏（核心线程不会退出，ThreadLocal 一直被持有）
-
-**错误示例**:
-```java
-// ❌ ThreadLocal 使用完毕后未清理
-static ThreadLocal<String> localVar = new ThreadLocal<>();
-
-public static void bad() {
-    localVar.set("value");
-    try {
-        // 业务代码
-    } finally {
-        // 没有清理！
-        LOGGER.info("finish");
-    }
-}
-```
-
-**正确示例**:
-```java
-// ✅ 在 finally 中调用 remove() 清理
-static ThreadLocal<String> localVar = new ThreadLocal<>();
-
-public static void good() {
-    localVar.set("value");
-    try {
-        // 业务代码
-    } finally {
-        localVar.remove();  // 必须清理
-        LOGGER.info("finish");
-    }
-}
-```
-
-> ⚠️ **注意**: `localVar.set(null)` 不被视为清理，仍会导致内存泄露，必须使用 `remove()`。
-
-### 3.2 禁止使用无界线程池
-
-**说明**: 无界线程池在极端大流量下会导致：
-- 阻塞导致服务响应超时
-- 系统资源得不到及时释放
-- 内存泄漏 OOM
-
-**错误示例**:
-```java
-// ❌ 无界线程池
-Executors.newCachedThreadPool();  // maximumPoolSize 为 Integer.MAX_VALUE
-
-// ❌ 使用无界队列
-Executors.newFixedThreadPool();  // 实际使用 new LinkedBlockingQueue<Runnable>()
-```
-
-**正确示例**:
-```java
-// ✅ 使用有界队列线程池
-ThreadPoolExecutor threadPoolExecutor = new ThreadPoolExecutor(
-    10,    // corePoolSize
-    50,    // maximumPoolSize
-    60,    // keepAliveTime
-    TimeUnit.SECONDS,
-    new LinkedBlockingQueue<>(100)  // 有界队列
-);
-```
-
----
-
-## 4. 数据库
-
-### 4.1 禁止使用 SELECT *
-
-**说明**: 使用 `SELECT *` 存在以下问题：
-- 性能问题：检索不必要的列，增加网络负载
-- 安全性问题：表结构变化可能导致应用错误
-- 可读性问题：代码不清晰，难以维护
-
-**错误示例**:
-```xml
-<!-- ❌ 使用 SELECT * -->
-<select id="getUser" parameterType="int" resultType="UserInfo">
-    select * from user_info where id = #{id}
-</select>
-```
-
-**正确示例**:
-```xml
-<!-- ✅ 指定具体的列名 -->
-<select id="getUser" parameterType="int" resultType="String">
-    select phone_num, email from user_info where id = #{id}
-</select>
-```
-
-### 4.2 使用参数化查询防止 SQL 注入
-
-**说明**: 必须使用参数化查询，禁止字符串拼接 SQL。
-
-**错误示例**:
-```xml
-<!-- ❌ 使用 ${}，存在 SQL 注入风险 -->
-<select id="getUserById" resultMap="UserMap" parameterType="java.util.String">
-    select id,username from t_user_info where id='${id}'
-</select>
-```
-
-**正确示例**:
-```xml
-<!-- ✅ 使用 #{} 参数化查询 -->
-<select id="getUserById" resultMap="UserMap" parameterType="java.util.String">
-    select id,username from t_user_info where id=#{id}
-</select>
-```
-
----
-
-## 5. 国际化
-
-### 5.1 必须在日期时间转换中设置时区
-
-**说明**: 如果想支持国际化时间，必须指定时区。
-
-**错误示例**:
-```java
-// ❌ 没有设置时区
-public Date bad(final String format, final String dateStr) throws ParseException {
-    SimpleDateFormat simpleDateFormat = new SimpleDateFormat();
-    simpleDateFormat.applyPattern(format);
-    return simpleDateFormat.parse(dateStr);
-}
-```
-
-**正确示例**:
-```java
-// ✅ 通过 setTimeZone 设置时区
-public Date good(final String format, final String dateStr) throws ParseException {
-    SimpleDateFormat simpleDateFormat = new SimpleDateFormat();
-    simpleDateFormat.setTimeZone(TimeZone.getTimeZone("Asia/Shanghai"));
-    simpleDateFormat.applyPattern(format);
-    simpleDateFormat.setLenient(false);
-    return simpleDateFormat.parse(dateStr);
-}
-```
-
----
-
-## 6. 安全
-
-### 6.1 验证反序列化的输入数据
-
-**说明**: 必须验证要反序列化的不受信任的输入，确保序列化数据仅包含受信任的类，防止远程代码执行漏洞。
-
-**正确示例**:
-```java
-// ✅ 通过白名单验证要反序列化的数据
-class WhitelistedObjectInputStream extends ObjectInputStream {
-    public Set whitelist;
-
-    public WhitelistedObjectInputStream(InputStream inputStream, Set wl) throws IOException {
-        super(inputStream);
-        whitelist = wl;
-    }
-
-    @Override
-    protected Class<?> resolveClass(ObjectStreamClass cls) throws IOException, ClassNotFoundException {
-        if (!whitelist.contains(cls.getName())) {
-            throw new InvalidClassException("Unexpected serialized class", cls.getName());
-        }
-        return super.resolveClass(cls);
-    }
-}
-```
-
-### 6.2 必须做好接口权限控制
-
-**说明**: 防范水平越权、垂直越权、未授权访问等漏洞。
-
-**水平越权防范**:
-```java
-// ✅ 增加权限校验
-@RequestMapping(value="/delete/{id}")
-public Object remove(@PathVariable Long id) {
-    if (WebUtils.isLogged()) {
-        // 增加权限校验：判断提交的数据是否属于当前登录用户
-        if (!checkPermission(id, WebUtils.getLoggedUserId())) {
-            return error("无权限删除此记录");
-        }
-        this.service.remove(id, WebUtils.getLoggedUserId());
-        return success("删除成功");
-    }
-    return error("用户未登录");
-}
-```
-
-### 6.3 禁止使用存在严重安全风险的组件
-
-**禁用组件列表**:
-- `xalan:xalan`
-- `org.jolokia:jolokia-core`
-- `org.apache.dubbo:dubbo`
-- `com.alibaba:dubbo`
-- `com.alibaba.fastjson2:fastjson2`
-- `com.alibaba:fastjson`（及其相关变体）
-- `org.apache.druid:druid-core`
-
----
-
-## 7. 日志打印
-
-### 7.1 必须使用 LogUtil 进行日志打印
-
-**说明**: 监控系统通过日志进行监控配置。为了确保链路追踪和监控的有效性，必须使用 `LogUtil` 工具类进行日志打印，它会自动添加 TraceId。
-
-**导入路径**:
-```java
-import com.example.common.util.log.LogUtil;
-import com.alibaba.common.logging.Logger;
-import com.alibaba.common.logging.LoggerFactory;
-```
-
-**Logger 定义**:
-```java
-// 使用 LoggerFileNames 定义 Logger（推荐，便于日志分类）
-private static final Logger LOGGER = LoggerFactory.getLogger(LoggerFileNames.BIZ_BUSINESS);
-
-// 或使用类名
-private static final Logger LOGGER = LoggerFactory.getLogger(YourClass.class);
-```
-
-**日志打印方式**:
-
-```java
-// ✅ info 日志 - 无参数
-LogUtil.info(LOGGER, "消息内容");
-
-// ✅ info 日志 - 带参数（使用 {0}, {1} 占位符）
-LogUtil.info(LOGGER, "处理成功，id={0}, userId={1}", id, userId);
-
-// ✅ warn 日志
-LogUtil.warn(LOGGER, "余额不足，userId={0}, balance={1}", userId, balance);
-
-// ✅ error 日志 - 带异常
-LogUtil.error(e, LOGGER, "处理异常，id={0}", id);
-
-// ✅ error 日志 - 不带异常
-LogUtil.error(LOGGER, "参数校验失败，request={0}", request);
-
-// ✅ debug 日志
-LogUtil.debug(LOGGER, "调试信息，data={0}", data);
-```
-
-**错误示例**:
-```java
-// ❌ 直接使用 logger 打印，无 TraceId
-LOGGER.info("处理成功，id=" + id);
-
-// ❌ 使用 System.out
-System.out.println("处理成功");
-
-// ❌ 使用字符串拼接而非占位符
-LogUtil.info(LOGGER, "处理成功，id=" + id);  // 应使用 {0} 占位符
-```
-
-### 7.2 日志打印最佳实践
-
-**1. 关键业务节点必须打印日志**:
-```java
-// 入口日志
-LogUtil.info(LOGGER, "【开始处理】id={0}, userId={1}", id, userId);
-
-// 关键状态变更
-LogUtil.info(LOGGER, "【状态变更】id={0}, oldStatus={1}, newStatus={2}",
-    id, oldStatus, newStatus);
-
-// 出口日志
-LogUtil.info(LOGGER, "【处理完成】id={0}, result={1}", id, result);
-```
-
-**2. 异常日志必须包含异常堆栈**:
-```java
-try {
-    // 业务代码
-} catch (Exception e) {
-    // ✅ 正确：包含异常对象，会打印完整堆栈
-    LogUtil.error(e, LOGGER, "处理异常，id={0}", id);
-
-    // ❌ 错误：丢失异常堆栈
-    LogUtil.error(LOGGER, "处理异常，id={0}, error={1}", id, e.getMessage());
-}
-```
-
-**3. 日志级别使用规范**:
-
-| 级别 | 使用场景 |
-|------|---------|
-| ERROR | 影响业务的异常、需要人工介入处理的问题 |
-| WARN | 可恢复的异常、不符合预期但不影响业务继续运行 |
-| INFO | 关键业务流程、状态变更、外部调用 |
-| DEBUG | 详细的调试信息，生产环境一般关闭 |
-
-**4. 日志内容规范**:
-- 使用中文方括号标记模块：`【开始处理】`、`【状态变更】`
-- 包含关键业务字段：id、userId、tradeId 等
-- 避免打印敏感信息（密码、身份证号、银行卡号等）
-
----
-
-## 8. 监控规范
-
-### 8.1 监控实现方式
-
-监控通过 **监控平台** + **日志打印** 实现：
-
-1. **业务代码打印日志**: 使用 `LogUtil` 按规范格式打印
-2. **配置监控规则**: 在监控平台配置日志关键字匹配规则
-3. **告警触发**: 当日志匹配规则时触发告警
-
-### 8.2 监控日志打印规范
-
-**1. 业务监控日志格式**:
-```java
-// 成功监控
-LogUtil.info(LOGGER, "[MONITOR][SUCCESS] id={0}, amount={1}", id, amount);
-
-// 失败监控
-LogUtil.error(LOGGER, "[MONITOR][FAIL] id={0}, errorCode={1}, errorMsg={2}",
-    id, errorCode, errorMsg);
-```
-
-**2. 可监控的关键业务节点**:
-- 交易下单成功/失败
-- 支付成功/失败
-- 确认成功/失败
-- 退款成功/失败
-- 外部接口调用超时/失败
-- 数值核对异常
-- 状态机异常流转
-
----
-
-## 9. 编码基础
-
-### 9.1 禁止在父子类中存在同名属性
-
-**说明**: 父子类存在同名属性时，可能导致：
-- 框架注入时仅注入子类属性，父类属性为 null，造成 NPE
-- 父类方法访问父类属性（未注入），子类方法访问子类属性（已注入），行为不一致
-
-**错误示例**:
-```java
-// ❌ 父子类存在同名属性
-public class Task {
-    private String name;
-}
-
-public class PATask extends Task {
-    private String name;  // 同名！
-}
-```
-
-**正确示例**:
-```java
-// ✅ 使用不同的属性名
-public class Task {
-    private String taskName;
-}
-
-public class PATask extends Task {
-    private String subTaskName;
-}
-```
-
----
-
-## 10. 命名规范
-
-### 10.1 基本命名规则
-
-| 类型 | 规则 | 示例 |
-|------|------|------|
-| 类名 | PascalCase | `TradeOrder`, `UserService` |
-| 方法名 | camelCase | `createOrder`, `validateUser` |
-| 变量名 | camelCase | `orderId`, `userBalance` |
-| 常量 | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT`, `DEFAULT_TIMEOUT` |
-| 包名 | 全小写 | `com.example.trade.biz` |
-
-### 10.2 有意义的命名
-
-- 类名应该是名词：`Order`, `UserService`
-- 方法名应该是动词或动词短语：`createOrder`, `isValid`
-- 布尔变量应该使用 is/has/can 前缀：`isSuccess`, `hasPermission`
-- 避免使用缩写（除非是通用缩写如 id, url）
-
----
-
-## 附录：禁止事项速查表
-
-| 类型 | 禁止事项 | 正确做法 |
-|------|---------|---------|
-| 数值计算 | 使用 float/double | 使用 Decimal/BigDecimal 类 |
-| 数据更新 | 不加锁直接更新 | 一锁二判三更新 |
-| 异常处理 | 空 catch 块 | 记录日志并处理 |
-| 异步方法 | 不捕获异常 | try-catch 或 AsyncResult |
-| ThreadLocal | 不清理 | finally 中 remove() |
-| 线程池 | 无界线程池 | 有界线程池 (队列≤100) |
-| SQL | SELECT * | 指定列名 |
-| SQL | 使用 ${} | 使用 #{} |
-| 日志 | 直接用 logger | 使用 LogUtil |
-| 父子类 | 同名属性 | 使用不同属性名 |
-
----
-
-## 11. 面向对象设计原则
-
-> **说明**: 遵循 SOLID 原则和领域驱动设计 (DDD)，编写高内聚、低耦合、易维护的代码
-
-### 11.1 单一职责原则 (SRP - Single Responsibility Principle)
-
-**原则**: 一个类只负责一个功能领域中的一项职责，只有一个引起它变化的原因。
-
-**错误示例**:
-```java
-// ❌ 一个类承担多种职责
-public class OrderService {
-    public void createOrder(Order order) { /* 创建订单 */ }
-    public void sendEmail(Order order) { /* 发送邮件 */ }
-    public String generateReport(List<Order> orders) { /* 生成报表 */ }
-    public void exportToExcel(List<Order> orders) { /* 导出 Excel */ }
-}
-```
-
-**正确示例**:
-```java
-// ✅ 职责分离
-public class OrderService {
-    public void createOrder(Order order) { /* 创建订单 */ }
-}
-
-public class OrderNotificationService {
-    public void sendOrderEmail(Order order) { /* 发送订单邮件 */ }
-}
-
-public class OrderReportService {
-    public String generateReport(List<Order> orders) { /* 生成报表 */ }
-    public void exportToExcel(List<Order> orders) { /* 导出 Excel */ }
-}
-```
-
-### 11.2 开闭原则 (OCP - Open/Closed Principle)
-
-**原则**: 对扩展开放，对修改关闭。新增功能通过扩展实现，而非修改现有代码。
-
-**错误示例**:
-```java
-// ❌ 每新增支付方式都要修改这个方法
-public class PaymentService {
-    public void pay(String payType, Money amount) {
-        if ("THIRD_PARTY".equals(payType)) {
-            // 第三方支付
-        } else if ("SCAN_CODE".equals(payType)) {
-            // 扫码支付
-        } else if ("BANK".equals(payType)) {
-            // 银行卡支付
-        }
-        // 新增支付方式需要修改此处...
-    }
-}
-```
-
-**正确示例**:
-```java
-// ✅ 使用策略模式，新增支付方式只需添加新的实现类
-public interface PaymentStrategy {
-    void pay(Money amount);
-    String getPayType();
-}
-
-@Component
-public class ThirdPartyPayStrategy implements PaymentStrategy {
-    @Override
-    public void pay(Money amount) { /* 第三方支付 */ }
-    @Override
-    public String getPayType() { return "THIRD_PARTY"; }
-}
-
-@Component
-public class ScanCodePayStrategy implements PaymentStrategy {
-    @Override
-    public void pay(Money amount) { /* 扫码支付 */ }
-    @Override
-    public String getPayType() { return "SCAN_CODE"; }
-}
-
-@Service
-public class PaymentService {
-    private final Map<String, PaymentStrategy> strategies;
-
-    public PaymentService(List<PaymentStrategy> strategyList) {
-        this.strategies = strategyList.stream()
-            .collect(Collectors.toMap(PaymentStrategy::getPayType, s -> s));
-    }
-
-    public void pay(String payType, Money amount) {
-        PaymentStrategy strategy = strategies.get(payType);
-        if (strategy == null) {
-            throw new BusinessException("不支持的支付方式：" + payType);
-        }
-        strategy.pay(amount);
-    }
-}
-```
-
-### 11.3 里氏替换原则 (LSP - Liskov Substitution Principle)
-
-**原则**: 子类必须能够替换其父类，程序行为不变。
-
-**错误示例**:
-```java
-// ❌ 正方形继承矩形，违反里氏替换
-public class Rectangle {
-    protected int width;
-    protected int height;
-
-    public void setWidth(int width) { this.width = width; }
-    public void setHeight(int height) { this.height = height; }
-    public int getArea() { return width * height; }
-}
-
-public class Square extends Rectangle {
-    @Override
-    public void setWidth(int width) {
-        this.width = width;
-        this.height = width;  // 违反父类行为预期
-    }
-    @Override
-    public void setHeight(int height) {
-        this.width = height;
-        this.height = height;  // 违反父类行为预期
-    }
-}
-```
-
-**正确示例**:
-```java
-// ✅ 使用组合或独立抽象
-public interface Shape {
-    int getArea();
-}
-
-public class Rectangle implements Shape {
-    private int width;
-    private int height;
-
-    public Rectangle(int width, int height) {
-        this.width = width;
-        this.height = height;
-    }
-
-    @Override
-    public int getArea() { return width * height; }
-}
-
-public class Square implements Shape {
-    private int side;
-
-    public Square(int side) { this.side = side; }
-
-    @Override
-    public int getArea() { return side * side; }
-}
-```
-
-### 11.4 接口隔离原则 (ISP - Interface Segregation Principle)
-
-**原则**: 客户端不应该依赖它不需要的接口。接口应细粒度，避免"胖接口"。
-
-**错误示例**:
-```java
-// ❌ 胖接口，强迫实现类实现不需要的方法
-public interface OrderService {
-    void createOrder(Order order);
-    void cancelOrder(Long orderId);
-    void queryOrder(Long orderId);
-    void exportOrderReport(List<Long> orderIds);  // 不是所有实现都需要
-    void syncOrderToThirdParty(Order order);       // 不是所有实现都需要
-}
-```
-
-**正确示例**:
-```java
-// ✅ 接口细粒度拆分
-public interface OrderCommandService {
-    void createOrder(Order order);
-    void cancelOrder(Long orderId);
-}
-
-public interface OrderQueryService {
-    Order queryOrder(Long orderId);
-}
-
-public interface OrderReportService {
-    void exportOrderReport(List<Long> orderIds);
-}
-
-public interface OrderSyncService {
-    void syncOrderToThirdParty(Order order);
-}
-```
-
-### 11.5 依赖倒置原则 (DIP - Dependency Inversion Principle)
-
-**原则**: 高层模块不依赖低层模块，都依赖抽象。面向接口编程。
-
-**错误示例**:
-```java
-// ❌ 高层模块直接依赖低层具体实现
-public class OrderService {
-    private MySQLOrderRepository repository = new MySQLOrderRepository();  // 直接依赖具体实现
-
-    public void createOrder(Order order) {
-        repository.save(order);
-    }
-}
-```
-
-**正确示例**:
-```java
-// ✅ 依赖抽象，通过依赖注入
-public interface OrderRepository {
-    void save(Order order);
-    Order findById(Long id);
-}
-
-@Repository
-public class MySQLOrderRepository implements OrderRepository {
-    @Override
-    public void save(Order order) { /* MySQL 实现 */ }
-    @Override
-    public Order findById(Long id) { /* MySQL 实现 */ }
-}
-
-@Service
-public class OrderService {
-    private final OrderRepository repository;  // 依赖抽象
-
-    public OrderService(OrderRepository repository) {  // 构造器注入
-        this.repository = repository;
-    }
-
-    public void createOrder(Order order) {
-        repository.save(order);
-    }
-}
-```
-
-### 11.6 领域驱动设计原则 (DDD)
-
-#### 11.6.1 聚合根设计
-
-**聚合根 (Aggregate Root)**: 作为事务一致性边界，外部只能通过聚合根访问内部实体。
-
-```java
-// ✅ 聚合根示例：交易订单
-public class TradeOrder {
-    private Long orderId;
-    private String userId;
-    private OrderStatus status;
-    private Money amount;
-    private List<TradePay> payments;  // 内部实体，外部不直接访问
-
-    // 业务方法内聚到领域对象
-    public void confirm() {
-        if (this.status != OrderStatus.PAYING) {
-            throw new BusinessException("订单状态不允许确认");
-        }
-        this.status = OrderStatus.SUCCESS;
-    }
-
-    public void addPayment(TradePay payment) {
-        // 通过聚合根管理内部实体
-        this.payments.add(payment);
-    }
-}
-```
-
-#### 11.6.2 业务逻辑内聚
-
-**原则**: 核心业务逻辑放在领域对象中，而非 Service 层。Service 层负责编排和协调。
-
-**错误示例**:
-```java
-// ❌ 贫血模型：领域对象只有 getter/setter，业务逻辑在 Service
-public class Order {
-    private Long id;
-    private OrderStatus status;
-    // 只有 getter/setter，无业务逻辑
-}
-
-public class OrderService {
-    public void confirmOrder(Long orderId) {
-        Order order = repository.findById(orderId);
-        if (order.getStatus() != OrderStatus.PAYING) {  // 业务逻辑泄露到 Service
-            throw new BusinessException("订单状态不允许确认");
-        }
-        order.setStatus(OrderStatus.SUCCESS);  // 直接修改状态
-        repository.save(order);
-    }
-}
-```
-
-**正确示例**:
-```java
-// ✅ 充血模型：业务逻辑内聚到领域对象
-public class Order {
-    private Long id;
-    private OrderStatus status;
-
-    // 业务逻辑内聚
-    public void confirm() {
-        if (this.status != OrderStatus.PAYING) {
-            throw new BusinessException("订单状态不允许确认");
-        }
-        this.status = OrderStatus.SUCCESS;
-    }
-
-    public boolean canCancel() {
-        return this.status == OrderStatus.INIT || this.status == OrderStatus.PAYING;
-    }
-}
-
-public class OrderService {
-    public void confirmOrder(Long orderId) {
-        Order order = repository.findById(orderId);
-        order.confirm();  // 调用领域对象的业务方法
-        repository.save(order);
-    }
-}
-```
-
-### 11.7 面向对象设计速查表
-
-| 原则 | 核心要点 | 违反信号 |
-|------|---------|---------|
-| SRP | 一个类一个职责 | 类过大 (>500 行)、方法过多 (>20 个)、职责不相关 |
-| OCP | 扩展而非修改 | 新增功能需修改核心类、大量 if-else/switch |
-| LSP | 子类可替换父类 | 子类覆盖父类方法改变行为、子类抛出父类不抛的异常 |
-| ISP | 接口细粒度 | 接口方法过多、实现类有空方法或抛 UnsupportedOperationException |
-| DIP | 依赖抽象 | new 具体类、直接依赖第三方 SDK 类 |
-| DDD | 业务逻辑内聚 | 贫血模型 (只有 getter/setter)、Service 层过重 |
-
----
-
-**维护者**: AutoSpec 团队
-**反馈渠道**: 知识库 Git 仓库 Issue
-**关联文档**: `knowledge/07-standards/02-data-consistency.md`, `knowledge/07-standards/01-code-review.md`