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

package/skills/meritdata-platform-data-access-review/references/anti-patterns.md

@@ -1,287 +0,0 @@
-# 反模式库（data-access-review）
-
-> 历史项目触发的真实反模式案例。每条含：场景 + 代码 + 后果 + 修复。
-
----
-
-## 1. PF_ 平台表映射（§1.1）
-
-### 1.1 案例 A：业务库映射平台表
-
-**场景**：2026-03 项目，业务库直接映射 `PF_USER`。
-
-```java
-// ❌ 错
-@Entity
-@TableName("PF_USER")
-public class UserEntity {
-    private String id;
-    private String loginName;
-}
-```
-
-**后果**：
-- 平台升级失败（schema 变更冲突）
-- 数据库耦合，跨库事务
-- 性能压力转嫁
-
-**修复**：
-
-```java
-// ✅ 正确
-@FeignClient(name = "cloud-system-manage")
-public interface IUserClient {
-    @GetMapping("/users/{id}")
-    UserDTO getById(@PathVariable String id);
-}
-```
-
-### 1.2 案例 B：跨库 JOIN
-
-```sql
--- ❌ 错
-SELECT o.*, u.real_name
-FROM t_order o
-JOIN PF_USER u ON o.user_id = u.id
-WHERE o.status = 'PAID';
-```
-
-**修复**：应用层 join（Feign 批量 + 内存 join）。
-
----
-
-## 2. 分页循环 Feign（§1.2）
-
-### 2.1 案例 A：循环调用 userClient
-
-**场景**：2026-04 项目，订单列表渲染时 N+1 Feign。
-
-```java
-// ❌ 错
-@GetMapping("/orders")
-public List<OrderVO> list() {
-    List<Order> orders = orderRepository.findAll();
-    for (Order o : orders) {
-        UserDTO user = userClient.getById(o.getUserId());  // N 次 Feign
-        o.setUserName(user.getRealName());
-    }
-    return orders;
-}
-```
-
-**后果**：
-- 1000 个订单 → 1000 次 Feign 调用
-- RT 从 100ms 变成 30s
-- 用户看到白屏
-
-**修复**：
-
-```java
-// ✅ 正确：批量装配
-@GetMapping("/orders")
-public List<OrderVO> list() {
-    List<Order> orders = orderRepository.findAll();
-
-    List<String> userIds = orders.stream()
-        .map(Order::getUserId).distinct()
-        .collect(Collectors.toList());
-
-    Map<String, UserDTO> userMap = userClient.listByIds(userIds).stream()
-        .collect(Collectors.toMap(UserDTO::getUserId, Function.identity()));
-
-    return orders.stream().map(o -> {
-        OrderVO vo = OrderVO.from(o);
-        UserDTO user = userMap.get(o.getUserId());
-        vo.setUserName(user != null ? user.getRealName() : "未知");
-        return vo;
-    }).collect(Collectors.toList());
-}
-```
-
-### 2.2 案例 B：嵌套循环
-
-```java
-// ❌ 错
-for (Dept dept : depts) {
-    for (User user : dept.getUsers()) {
-        for (Role role : user.getRoles()) {
-            // ... 每层都 Feign
-        }
-    }
-}
-```
-
-**修复**：批量取所有 role IDs → 一次 Feign → 内存 join。
-
----
-
-## 3. 平台 Entity 引用（§1.3）
-
-### 3.1 案例 A：二开 import 平台 Entity
-
-**场景**：2026-05 项目，二开 Service 直接操作平台 Entity。
-
-```java
-// ❌ 错
-import com.meritdata.cloud.platform.entity.User;
-import com.meritdata.cloud.platform.repository.UserRepository;
-
-@Service
-public class UserService {
-    @Autowired
-    private UserRepository userRepository;  // 平台 Repository
-
-    public void updateUser(User user) {
-        userRepository.save(user);
-    }
-}
-```
-
-**后果**：
-- 二开服务与平台 Entity 强耦合
-- 平台 Entity 字段变更 → 二开代码编译失败
-- 平台独立部署受限
-
-**修复**：
-
-```java
-// ✅ 正确：DTO 转换
-@FeignClient(name = "cloud-system-manage")
-public interface IUserClient {
-    @PostMapping("/users")
-    UserDTO createUser(@RequestBody UserDTO user);
-}
-
-@Service
-public class UserService {
-    @Autowired
-    private IUserClient userClient;
-
-    public void updateUser(UserDTO user) {
-        userClient.updateUser(user);
-    }
-}
-```
-
-### 3.2 案例 B：Entity extends 平台 Entity
-
-```java
-// ❌ 错
-@Entity
-public class CustomUser extends User {  // 继承平台 Entity
-    private String customField;
-}
-```
-
-**修复**：完全独立建表 + DTO 转换。
-
----
-
-## 4. 空集合掩盖异常（§1.4）
-
-### 4.1 案例 A：Feign 失败返回空
-
-**场景**：2026-06 项目，平台用户服务短暂不可用，业务返回空列表。
-
-```java
-// ❌ 错
-@GetMapping("/orders")
-public List<OrderVO> list() {
-    try {
-        List<Order> orders = orderRepository.findAll();
-        List<String> userIds = orders.stream().map(Order::getUserId).collect(toList());
-        List<UserDTO> users = userClient.listByIds(userIds);  // Feign 失败
-        // ...
-    } catch (Exception e) {
-        return Collections.emptyList();  // 掩盖故障
-    }
-}
-```
-
-**后果**：
-- 平台故障时业务页面白屏
-- 监控无告警（异常被吃掉）
-- 故障定位耗时长
-
-**修复**：
-
-```java
-// ✅ 正确：显式异常
-@GetMapping("/orders")
-public List<OrderVO> list() {
-    try {
-        // ...
-    } catch (FeignException e) {
-        log.error("平台用户服务调用失败", e);
-        alertService.send("USER_SERVICE_UNAVAILABLE", e);
-        throw new ServiceException("USER_SERVICE_UNAVAILABLE", e);
-    }
-}
-```
-
-### 4.2 案例 B：空 catch
-
-```java
-// ❌ 错
-try {
-    userClient.updateUser(user);
-} catch (Exception e) {
-    // 吞掉
-}
-```
-
-**修复**：至少 log.error + 考虑 rethrow。
-
----
-
-## 5. 其他反模式（非铁律）
-
-### 5.1 SQL 拼接
-
-```java
-// ❌ 错
-String sql = "SELECT * FROM t_user WHERE name = '" + name + "'";
-// → SQL 注入
-```
-
-✅ 用 `@Param` / `PreparedStatement`。
-
-### 5.2 循环内 DB 查询
-
-```java
-// ❌ 错
-for (String id : ids) {
-    userRepository.findById(id);  // 100 次查询
-}
-```
-
-✅ `findAllById(ids)`。
-
-### 5.3 同步 Feign 阻塞
-
-```java
-// ❌ 错
-UserDTO user = userClient.getById(id);  // 阻塞业务
-```
-
-✅ 异步 Feign 或预加载。
-
----
-
-## 6. 总结表
-
-| 铁律 | 反模式 | 案例 | 严重度 |
-|------|--------|------|--------|
-| §1.1 | `@TableName("PF_")` | 2026-03 项目 | 🔴 |
-| §1.1 | 跨库 JOIN | 持续多项目 | 🔴 |
-| §1.2 | 循环 + Feign | 2026-04 项目 | 🔴 |
-| §1.3 | import 平台 Entity | 2026-05 项目 | 🔴 |
-| §1.3 | Entity 继承 | 持续 | 🔴 |
-| §1.4 | catch + emptyList | 2026-06 项目 | 🔴 |
-
-## 7. 关联阅读
-
-- [guide.md](guide.md) — 审查清单
-- [ci-scan.md](ci-scan.md) — CI 脚本
-- [rules/meritdata-platform-data-boundary.md](../../rules/meritdata-platform-data-boundary.md)
-- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-data-access-review/references/ci-scan.md

@@ -1,225 +0,0 @@
-# CI 扫描脚本（data-access-review）
-
-> 集成到 CI 的自动化扫描脚本，PR 触发时执行。
-
----
-
-## 1. 集成方式
-
-### 1.1 GitLab CI
-
-```yaml
-# .gitlab-ci.yml
-data-access-review:
-  stage: check
-  script:
-    - bash scripts/scan-data-access.sh
-  rules:
-    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
-```
-
-### 1.2 GitHub Actions
-
-```yaml
-# .github/workflows/data-access-review.yml
-name: Data Access Review
-on: [pull_request]
-
-jobs:
-  scan:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - run: bash scripts/scan-data-access.sh
-```
-
-## 2. 主脚本
-
-```bash
-#!/bin/bash
-# scripts/scan-data-access.sh
-# 数据访问 4 铁律扫描
-
-set -e
-SCAN_DIR="${1:-src/main}"
-EXIT_CODE=0
-
-echo "========================================="
-echo "  数据访问 4 铁律扫描"
-echo "========================================="
-
-# §1.1 PF_ 平台表
-echo ""
-echo "[§1.1] 检查 PF_ 平台表映射..."
-if grep -rE '@TableName\("PF_' "$SCAN_DIR"/java/ 2>/dev/null; then
-    echo "❌ 发现 PF_ 映射，违反铁律 1.1"
-    EXIT_CODE=1
-else
-    echo "✅ 未发现 PF_ 映射"
-fi
-
-# §1.1 跨库 JOIN
-echo ""
-echo "[§1.1] 检查跨库 JOIN 平台表..."
-if grep -rE 'JOIN\s+PF_' "$SCAN_DIR"/resources/mapper/ 2>/dev/null; then
-    echo "❌ 发现跨库 JOIN，违反铁律 1.1"
-    EXIT_CODE=1
-else
-    echo "✅ 未发现跨库 JOIN"
-fi
-
-# §1.3 平台 Entity
-echo ""
-echo "[§1.3] 检查平台 Entity 直接 import..."
-if grep -r 'import com.meritdata.cloud.platform.entity' "$SCAN_DIR"/java/com/example/ 2>/dev/null; then
-    echo "❌ 二开项目不应直接 import 平台 Entity"
-    EXIT_CODE=1
-else
-    echo "✅ 未发现平台 Entity 直接引用"
-fi
-
-# §1.4 空集合掩盖（warn 不阻断）
-echo ""
-echo "[§1.4] 检查空集合掩盖异常..."
-if grep -rn 'catch.*Exception.*emptyList\|catch.*Exception.*Collections.empty' "$SCAN_DIR"/java/ 2>/dev/null | grep -v 'test/'; then
-    echo "⚠️ 疑似空集合掩盖异常，请人工 review"
-else
-    echo "✅ 未发现空集合掩盖"
-fi
-
-echo ""
-echo "========================================="
-if [ $EXIT_CODE -eq 0 ]; then
-    echo "  扫描通过 ✅"
-else
-    echo "  扫描失败 ❌（请修复后重新提交）"
-fi
-echo "========================================="
-
-exit $EXIT_CODE
-```
-
-## 3. 高级扫描
-
-### 3.1 N+1 检测（AST）
-
-```python
-#!/usr/bin/env python3
-# scripts/scan-n-plus-one.py
-"""
-检测循环 + Feign.method() 模式（N+1 查询）
-"""
-import os
-import re
-import sys
-
-PATTERN = re.compile(
-    r'for\s*\(.*?\)\s*{[^}]*?(feignClient|userClient|orgClient|menuClient)\.\w+\(',
-    re.DOTALL
-)
-
-def scan_file(path):
-    with open(path) as f:
-        content = f.read()
-    return PATTERN.findall(content)
-
-def main():
-    violations = []
-    for root, _, files in os.walk('src/main/java'):
-        for f in files:
-            if f.endswith('.java'):
-                path = os.path.join(root, f)
-                matches = scan_file(path)
-                if matches:
-                    violations.append((path, matches))
-
-    if violations:
-        print("❌ 发现 N+1 模式：")
-        for path, matches in violations:
-            print(f"  {path}: {matches}")
-        sys.exit(1)
-    print("✅ 未发现 N+1 模式")
-
-if __name__ == '__main__':
-    main()
-```
-
-### 3.2 SQL 注入检测
-
-```bash
-#!/bin/bash
-# 检测 SQL 拼接
-echo "[SQL 注入] 检查字符串拼接 SQL..."
-
-# 检测 ${...} 在 @Query 注解中
-if grep -rn '@Query.*\${' src/main/java/ 2>/dev/null; then
-    echo "❌ 发现 @Query 中使用 \${} 拼接 SQL"
-    exit 1
-fi
-
-# 检测 Statement.executeQuery(string)
-if grep -rn 'executeQuery(".*" + ' src/main/java/ 2>/dev/null; then
-    echo "❌ 发现字符串拼接执行 SQL"
-    exit 1
-fi
-
-echo "✅ SQL 注入扫描通过"
-```
-
-### 3.3 敏感信息检测
-
-```bash
-#!/bin/bash
-# 检测硬编码密钥/密码
-echo "[敏感信息] 检查硬编码密钥..."
-
-PATTERNS=(
-    'password.*=.*"[a-zA-Z0-9]{6,}"'
-    'secret.*=.*"[a-zA-Z0-9]{8,}"'
-    'apiKey.*=.*"[a-zA-Z0-9]{16,}"'
-)
-
-for p in "${PATTERNS[@]}"; do
-    if grep -rEn "$p" src/main/java/ 2>/dev/null | grep -v 'test/'; then
-        echo "⚠️ 疑似硬编码密钥"
-    fi
-done
-
-echo "✅ 敏感信息扫描完成"
-```
-
-## 4. SonarQube 集成
-
-```xml
-<!-- sonar-project.properties -->
-sonar.projectKey=your-2nd-service
-sonar.sources=src/main/java
-sonar.exclusions=**/test/**,**/generated/**
-sonar.java.binaries=target/classes
-
-# 自定义规则
-sonar.custom_rules.java.data-access=java-data-access.xml
-```
-
-## 5. 报告输出
-
-```bash
-# 输出 JSON 格式报告
-{
-  "scanTime": "2026-09-07T10:00:00Z",
-  "rules": {
-    "1.1_pf_prefix": {"passed": true, "violations": []},
-    "1.1_cross_db_join": {"passed": true, "violations": []},
-    "1.3_platform_entity": {"passed": false, "violations": [...]},
-    "1.4_empty_collection": {"passed": true, "warnings": [...]}
-  },
-  "overall": "FAIL"
-}
-```
-
-## 6. 关联阅读
-
-- [guide.md](guide.md) — 审查清单
-- [anti-patterns.md](anti-patterns.md) — 反模式库
-- [rules/meritdata-platform-data-boundary.md §3](../../rules/meritdata-platform-data-boundary.md)
-- [SKILL.md](../SKILL.md)