@alanwang-merit/meritdata-platform-skill-package 1.0.9 → 1.0.11

package/skills/meritdata-platform-code-spec/references/anti-patterns.md

@@ -1,533 +0,0 @@
-# 反模式 vs 正模式（code-spec）
-
-> **本文件与 rules/code-dev-rules.md §八.3 一一对应**。每条铁律给出：❌ 反模式代码 → ✅ 正模式代码 → 根因 → 真实踩坑案例。
->
-> **使用方法**：写代码时按目录逐项检查；PR review 时逐项打钩；CI 扫描时按 [validate-rules.md](validate-rules.md) 自动检测。
-
----
-
-## 1. 软删除实体反模式（核心反模式）
-
-### 1.1 唯一性校验未穿透软删除
-
-**铁律来源**：[rules §八.3 软删除实体](../../../../rules/code-dev-rules.md#83-code-spec-补充铁律编码层)
-
-**触发条件**：实体使用 `@SQLDelete` + `@Where(clause="deleted=false")` + 任意 `uk_xxx_no` 唯一约束。
-
-#### ❌ 反模式（业务查询看不到软删除记录）
-
-```java
-public void createProject(String projectNo) {
-    // JPQL 受 @Where 过滤，看不到软删除记录
-    if (projectRepo.findByProjectNo(projectNo).isPresent()) {
-        throw new ProjectNoDuplicateException();
-    }
-    Project p = new Project();
-    p.setProjectNo(projectNo);
-    projectRepo.save(p);  // 💥 INSERT 触发 SQLIntegrityConstraintViolationException 500
-}
-```
-
-#### ✅ 正模式（nativeQuery + findIncludingDeleted）
-
-```java
-public void createProject(String projectNo) {
-    // nativeQuery = true 的 findIncludingDeleted 穿透 @Where 过滤
-    if (projectRepo.findProjectNoIncludingDeleted(projectNo).isPresent()) {
-        throw new ProjectNoDuplicateException();
-    }
-    Project p = new Project();
-    p.setProjectNo(projectNo);
-    projectRepo.save(p);  // ✅ DB 唯一约束检查通过后才 INSERT
-}
-```
-
-**Repository 实现要点**：
-
-```java
-// ❌ 错（JPQL，受 @Where 过滤）
-@Query("SELECT p FROM Project p WHERE p.projectNo = :no")
-Optional<Project> findByProjectNo(@Param("no") String no);
-
-// ✅ 对（nativeQuery = true，穿透过滤）
-@Query(value = "SELECT * FROM t_project WHERE project_no = :no AND deleted = :deleted",
-       nativeQuery = true)
-Optional<Project> findProjectNoIncludingDeleted(@Param("no") String no,
-                                                  @Param("deleted") boolean deleted);
-```
-
-#### 根因
-
-DB 唯一约束 `uk_project_no` 包含所有记录（含软删除），但业务 JPQL 受 `@Where(clause="deleted=false")` 过滤，业务查询看不到软删除记录 → 校验放行 → INSERT 触发唯一约束异常 500。
-
-#### 真实踩坑案例
-
-- **2026-06-12 Project 模块**：新增项目时复用软删除的项目编号，校验通过但 INSERT 500
-- **2026-06-12 Customer 模块**：同样的反模式，连续触发两次
-
-完整案例与回归用例见 `docs/技术约束.md §6`。
-
-### 1.2 编号生成器查已用编号
-
-**铁律来源**：同 §八.3 软删除实体
-
-#### ❌ 反模式
-
-```java
-// XxxNoGenerator.generate() 内部
-List<String> usedNos = repo.findAllNosStartingWith(prefix);  // 受 @Where 过滤
-// → 软删除的编号被认为"未用" → 生成可能重复 → 触发唯一约束
-```
-
-#### ✅ 正模式
-
-```java
-List<String> usedNos = repo.findAllNosStartingWithIncludingDeleted(prefix, nativeQuery = true);
-// → 软删除的编号计入已用 → 生成新编号自动跳过
-```
-
-### 1.3 业务查询与全量查询必须成对出现
-
-**铁律来源**：同 §八.3
-
-**命名约定**：
-
-| 业务查询（受 @Where 过滤）| 全量查询（穿透 @Where）|
-|--------------------------|------------------------|
-| `findByProjectNo` | `findProjectNoIncludingDeleted` |
-| `findAllByCreateBy` | `findAllByCreateByIncludingDeleted` |
-| `findAllXxxStartingWith` | `findAllXxxStartingWithIncludingDeleted` |
-
-**禁止**：
-- ❌ 用 `findByXxx` 做唯一性校验
-- ❌ 用 `*IncludingDeleted` 方法做业务展示（业务展示只允许走业务查询）
-
----
-
-## 2. 循环与外部资源反模式
-
-**铁律来源**：[rules §四](../../../../rules/code-dev-rules.md#四流程控制) + §八.3
-
-### 2.1 循环内调数据库
-
-#### ❌ 反模式
-
-```java
-for (Order order : orders) {
-    User user = userDao.findById(order.getUserId());  // N 次查询
-    order.setUserName(user.getName());
-}
-```
-
-#### ✅ 正模式
-
-```java
-List<Long> userIds = orders.stream().map(Order::getUserId).distinct().collect(toList());
-Map<Long, User> userMap = userDao.findAllById(userIds).stream()
-    .collect(Collectors.toMap(User::getId, u -> u));
-orders.forEach(o -> {
-    User u = userMap.get(o.getUserId());
-    if (u != null) o.setUserName(u.getName());
-});
-```
-
-**理由**：N+1 查询导致响应时间随数据量线性恶化，数据库连接池耗尽。
-
-### 2.2 循环内调 Feign / HTTP
-
-#### ❌ 反模式
-
-```java
-for (int page = 1; page <= totalPages; page++) {
-    List<Order> orderList = orderRepo.findPage(page);
-    for (Order order : orderList) {
-        UserDTO user = userClient.getById(order.getUserId());  // N 次 Feign
-        order.setUserName(user.getName());
-    }
-}
-```
-
-#### ✅ 正模式
-
-```java
-// 一次 Feign 批量拉取
-List<Order> allOrders = orderRepo.findAll();
-Set<Long> userIds = allOrders.stream().map(Order::getUserId).collect(Collectors.toSet());
-Map<Long, UserDTO> userMap = userClient.listByIds(new ArrayList<>(userIds))
-    .stream().collect(Collectors.toMap(UserDTO::getId, u -> u));
-
-// 内存 join
-allOrders.forEach(o -> {
-    UserDTO u = userMap.get(o.getUserId());
-    if (u != null) o.setUserName(u.getName());
-});
-```
-
-**铁律 2 关联**：[data-boundary 反模式 §1.2](../meritdata-platform-data-boundary/references/anti-patterns.md#12-分页循环逐条-feign)
-
-### 2.3 循环内调 Redis / 缓存
-
-#### ❌ 反模式
-
-```java
-for (String key : keys) {
-    String value = redisTemplate.opsForValue().get(key);  // N 次 RTT
-    process(key, value);
-}
-```
-
-#### ✅ 正模式（pipeline）
-
-```java
-List<Object> values = redisTemplate.executePipelined((RedisCallback<Object>) connection -> {
-    for (String key : keys) {
-        connection.stringCommands().get(key.getBytes());
-    }
-    return null;
-});
-```
-
----
-
-## 3. 异常处理反模式
-
-**铁律来源**：[rules §五](../../../../rules/code-dev-rules.md#五异常处理) + §八.3
-
-### 3.1 吞异常
-
-#### ❌ 反模式
-
-```java
-try {
-    remoteCall();
-} catch (Exception e) {
-    return Collections.emptyList();  // 平台故障被掩盖
-}
-```
-
-#### ✅ 正模式
-
-```java
-try {
-    return remoteCall();
-} catch (FeignException e) {
-    log.error("远程调用失败, service={}, reason={}", serviceName, e.getMessage());
-    throw new ServiceException("REMOTE_FAIL", "调用XX服务失败", e);
-}
-```
-
-**铁律 4 关联**：[data-boundary 反模式 §4](../meritdata-platform-data-boundary/references/anti-patterns.md#4-掩盖平台故障)
-
-### 3.2 空 catch 块
-
-#### ❌ 反模式
-
-```java
-try {
-    riskyOperation();
-} catch (Exception e) {
-    // 静默吞掉
-}
-```
-
-#### ✅ 正模式（必须三选一）
-
-```java
-// 选项 1：日志 + 上抛
-try { riskyOperation(); }
-catch (Exception e) { log.error("操作失败", e); throw new ServiceException(...); }
-
-// 选项 2：日志 + 显式降级（业务允许时）
-try { riskyOperation(); }
-catch (Exception e) { log.warn("操作降级", e); return defaultValue(); }
-
-// 选项 3：精确捕获（不要用 Exception）
-try { riskyOperation(); }
-catch (IllegalArgumentException e) { /* 业务校验失败，已知 */ }
-```
-
-### 3.3 finally 中抛异常
-
-#### ❌ 反模式
-
-```java
-try { conn = getConnection(); } 
-finally { conn.close(); }  // close() 抛异常会覆盖 try 中的异常
-```
-
-#### ✅ 正模式（try-with-resources）
-
-```java
-try (Connection conn = getConnection();
-     PreparedStatement ps = conn.prepareStatement(sql)) {
-    ps.execute();
-}  // 自动按相反顺序关闭，异常不被覆盖
-```
-
----
-
-## 4. 敏感信息反模式
-
-**铁律来源**：[rules §六](../../../../rules/code-dev-rules.md#六敏感信息) + §八.3
-
-### 4.1 日志打印敏感字段
-
-#### ❌ 反模式
-
-```java
-log.info("user login: name={}, pwd={}", user.getName(), user.getPassword());
-log.debug("auth token: {}", token);
-log.info("principal: {}", SecurityContextHolder.getContext().getAuthentication());
-```
-
-#### ✅ 正模式
-
-```java
-log.info("user login: name={}, pwd=***", user.getName());
-// token / principal 严禁打印，如需调试用脱敏工具
-String maskedToken = SensitiveMasker.maskToken(token);  // 仅前4位+***
-```
-
-### 4.2 硬编码密钥
-
-#### ❌ 反模式
-
-```java
-private static final String SECRET_KEY = "abc123-meritdata-2024";
-private static final String DB_PASSWORD = "BigData.2018v6";
-```
-
-#### ✅ 正模式
-
-```java
-@Value("${app.crypto.sm4-key}")
-private String sm4Key;  // 从 Nacos 配置读取
-
-@NacosValue(value = "${db.password}", autoRefreshed = true)
-private String dbPassword;  // 加密配置项
-```
-
-**关联 skill**：`meritdata-platform-crypto-gm`、`meritdata-platform-config-item`
-
-### 4.3 异常信息泄露内部实现
-
-#### ❌ 反模式
-
-```java
-} catch (SQLException e) {
-    return Result.fail("SQL 错误: " + e.getMessage() + " 表: " + e.getSQLState());
-    // → 暴露表名、SQL 状态、数据库版本
-}
-```
-
-#### ✅ 正模式
-
-```java
-} catch (SQLException e) {
-    log.error("DB error, sqlState={}", e.getSQLState(), e);  // 详细日志内部保留
-    throw new ServiceException("DB_ERROR", "数据库操作失败");  // 用户只看到错误码
-}
-```
-
----
-
-## 5. 架构层反模式
-
-**铁律来源**：[rules §八.3 架构层](../../../../rules/code-dev-rules.md#83-code-spec-补充铁律编码层) + §重要提醒
-
-### 5.1 Controller / Service / Dao 层有成员变量
-
-#### ❌ 反模式
-
-```java
-@Service
-public class OrderService {
-    private User currentUser;  // 多线程下数据错乱
-    private OrderContext context;  // 线程不安全
-}
-```
-
-#### ✅ 正模式
-
-```java
-@Service
-public class OrderService {
-    // 只有 @Autowired 注入的 final 依赖
-    private final OrderRepo orderRepo;
-    private final UserClient userClient;
-
-    public void createOrder(OrderDTO dto) {
-        User currentUser = SessionUtils.getCurrentUser();  // 每次从上下文取
-        // ...
-    }
-}
-```
-
-**理由**：Controller/Service/Dao 由 Spring 单例管理，多线程共享；非 final 成员变量会引发线程安全问题。
-
-### 5.2 Shell 脚本 Windows 换行符
-
-#### ❌ 反模式（CRLF，部署到 Linux 失败）
-
-```bash
-#!/bin/bash\r\n
-echo "starting..."\r\n
-```
-
-#### ✅ 正模式（LF）
-
-```bash
-#!/bin/bash
-echo "starting..."
-```
-
-**CI 校验**：
-
-```bash
-file scripts/*.sh | grep CRLF && echo "❌ 含 CRLF 换行符" && exit 1
-```
-
-### 5.3 平台特定：GridView 参数处理
-
-#### ❌ 反模式（手动拼 SQL）
-
-```java
-@GetMapping("/list")
-public List<OrderVO> list(@RequestParam Map<String, String> params) {
-    String sql = "SELECT * FROM t_order WHERE 1=1";
-    if (params.get("status") != null) {
-        sql += " AND status = '" + params.get("status") + "'";  // SQL 注入
-    }
-    // ...
-}
-```
-
-#### ✅ 正模式（GridView + QueryDSL）
-
-```java
-@GetMapping("/list")
-public GridView<OrderVO> list(GridQuery query, @RequestParam(required = false) String status) {
-    BooleanBuilder where = new BooleanBuilder();
-    if (status != null) where.and(qOrder.status.eq(status));
-    List<OrderVO> list = queryFactory
-        .select(Projections.bean(OrderVO.class, qOrder.all()))
-        .from(qOrder)
-        .where(where)
-        .offset(query.getOffset())
-        .limit(query.getLimit())
-        .fetch();
-    return new GridView<>(list, totalCount);
-}
-```
-
----
-
-## 6. 平台特定规范
-
-### 6.1 ResultBody 响应包装
-
-#### ❌ 反模式
-
-```java
-@PostMapping("/create")
-public Order create(@RequestBody OrderDTO dto) {
-    return orderService.create(dto);  // 平台前端无法统一处理错误
-}
-```
-
-#### ✅ 正模式
-
-```java
-@PostMapping("/create")
-public ResultBody<OrderVO> create(@RequestBody OrderDTO dto) {
-    OrderVO vo = orderService.create(dto);
-    return ResultBody.success(vo);
-}
-```
-
-### 6.2 Swagger 注解
-
-#### ❌ 反模式（无注解）
-
-```java
-@GetMapping("/get")
-public UserVO get(Long id) { ... }  // Swagger 文档无字段说明
-```
-
-#### ✅ 正模式
-
-```java
-@ApiOperation("查询用户详情")
-@GetMapping("/get")
-public ResultBody<UserVO> get(
-    @ApiParam(value = "用户ID", required = true, example = "10001")
-    @RequestParam Long id
-) { ... }
-```
-
-### 6.3 二开业务表小写蛇形
-
-**铁律来源**：[rules §八.2](../../../../rules/code-dev-rules.md#82-业务建模规则domain-model) + §七
-
-#### ❌ 反模式（大写 / 驼峰）
-
-```sql
-CREATE TABLE PurchaseOrder (
-    orderNo VARCHAR(50),
-    createBy BIGINT,
-    createTime DATETIME
-);
-```
-
-#### ✅ 正模式（小写蛇形）
-
-```sql
-CREATE TABLE t_purchase_order (
-    order_no VARCHAR(50),
-    create_by BIGINT,
-    create_time DATETIME
-);
-```
-
-**实体类**（与表命名解耦）：
-
-```java
-@Entity
-@Table(name = "t_purchase_order")
-public class PurchaseOrder {
-    @Column(name = "order_no")
-    private String orderNo;
-
-    @Column(name = "create_by")
-    private Long createBy;
-}
-```
-
----
-
-## 7. 速查表
-
-| 铁律 | 反模式关键特征 | 正模式关键特征 |
-|------|--------------|--------------|
-| 软删除唯一性 | `findByXxx` 校验唯一性 | `findXxxIncludingDeleted(nativeQuery)` |
-| 软删除编号生成 | `findAllXxxStartingWith` | `findAllXxxStartingWithIncludingDeleted(nativeQuery)` |
-| 循环不调外部 | `for + findById` | `findAllById + 内存 join` |
-| 循环不调 Feign | `for + userClient.getById` | `userClient.listByIds + 内存 join` |
-| 异常不吞 | `catch + return emptyList` | `throw new ServiceException` |
-| 异常 finally | `try/finally close()` | `try-with-resources` |
-| 敏感信息 | `log.info("pwd={}", pwd)` | `log.info("pwd=***")` |
-| 密钥硬编码 | `private static final SECRET = "..."` | `@NacosValue` 注入 |
-| Controller 成员变量 | `@Service private User u;` | `private final` 依赖 |
-| Shell 换行符 | CRLF | LF |
-| GridView | `Map<String,String>` 接参 | `GridQuery` 专用对象 |
-| ResultBody | `return entity` | `return ResultBody.success(entity)` |
-| 二开表命名 | `PurchaseOrder` | `t_purchase_order` |
-
----
-
-## 8. 关联阅读
-
-- [validate-rules.md](validate-rules.md) — CI 自动化校验命令
-- [rules/code-dev-rules.md §八.3](../../../../rules/code-dev-rules.md#83-code-spec-补充铁律编码层) — 铁律摘要
-- [data-boundary anti-patterns](../meritdata-platform-data-boundary/references/anti-patterns.md) — 数据访问边界反模式
-- [domain-model anti-patterns](../meritdata-platform-domain-model/references/anti-patterns.md) — 业务建模反模式