junhong_cmp_fiber/openspec/changes/archive/2026-01-30-code-cleanup-docs-update/specs/ci-checks.md

CI 检查脚本规范

概述

本变更新增了自动化代码规范检查脚本，用于在 CI/CD 流程中检测规范违规。

检查脚本列表

1. Service 层错误处理检查

文件：scripts/check-service-errors.sh

用途：检查 Service 层是否使用 fmt.Errorf 对外返回错误

检查范围：

• 目录：internal/service/**/*.go
• 排除：测试文件（*_test.go）
• 排除：带有 // whitelist: 注释的行

检查逻辑：

FILES=$(find internal/service -name "*.go" -type f)
VIOLATIONS=$(grep -n "fmt\.Errorf" $FILES | grep -v "// whitelist:")

if [ -n "$VIOLATIONS" ]; then
    echo "❌ 发现 Service 层使用 fmt.Errorf"
    exit 1
fi

退出码：

• 0：检查通过
• 1：检查失败（发现违规）

白名单机制：

如果某处确实需要使用 fmt.Errorf（如内部调试），添加注释：

// 特殊场景：内部日志调试
debugErr := fmt.Errorf("debug info: %v", data) // whitelist:
logger.Debug("调试信息", zap.Error(debugErr))

2. 注释路径一致性检查

文件：scripts/check-comment-paths.sh

用途：检查 Handler 层注释中是否残留已弃用的 /api/v1 路径

检查范围：

• 目录：internal/handler/**/*.go
• 排除：测试文件（*_test.go）

检查逻辑：

VIOLATIONS=$(grep -rn "/api/v1" internal/handler/ | grep -v "_test.go")

if [ -n "$VIOLATIONS" ]; then
    echo "❌ 发现残留的 /api/v1 路径注释"
    exit 1
fi

退出码：

• 0：检查通过
• 1：检查失败（发现残留路径）

正确路径：

• /api/admin/*：后台管理接口
• /api/h5/*：H5 端接口
• /api/c/v1/*：个人客户接口

3. 统一检查脚本

文件：scripts/check-all.sh

用途：运行所有代码规范检查

检查流程：

set -e  # 任何检查失败立即退出

bash scripts/check-service-errors.sh
bash scripts/check-comment-paths.sh
# 未来可添加更多检查...

echo "✅ 所有检查通过"

使用场景：

• 本地开发：提交代码前运行
• CI/CD：自动化检查流程
• Pre-commit hook：提交前自动检查（可选）

脚本规范

输出格式

所有检查脚本应遵循统一的输出格式：

# 1. 开始提示
echo "🔍 检查 [检查项名称]..."

# 2. 检查逻辑
VIOLATIONS=$(检查命令)

# 3. 结果输出
if [ -n "$VIOLATIONS" ]; then
    echo ""
    echo "❌ 发现违规："
    echo "$VIOLATIONS"
    echo ""
    echo "修复建议："
    echo "  - 建议1"
    echo "  - 建议2"
    exit 1
fi

echo "✅ [检查项名称]检查通过"

错误消息规范

错误消息应包含：

1. 问题描述：明确说明发现了什么问题
2. 违规位置：文件路径和行号
3. 修复建议：如何修复这些问题
4. 白名单机制：如何豁免特殊场景（如适用）

示例：

❌ 发现 Service 层使用 fmt.Errorf：
internal/service/shop.go:45:    return fmt.Errorf("店铺不存在")
internal/service/account.go:78: return fmt.Errorf("创建失败: %w", err)

请使用以下方式替代：
  - 业务错误：errors.New(code, msg)
  - 系统错误：errors.Wrap(code, err, msg)

如果某处确实需要使用 fmt.Errorf（如内部调试），请添加注释：// whitelist:

脚本权限

所有脚本应添加执行权限：

chmod +x scripts/check-service-errors.sh
chmod +x scripts/check-comment-paths.sh
chmod +x scripts/check-all.sh

Shell 兼容性

脚本应使用 Bash 标准语法，兼容 Linux 和 macOS：

• 使用 #!/bin/bash 作为 shebang
• 避免使用非标准工具（仅依赖 grep、find、bash 等）
• 使用 set -e 确保错误自动退出

CI 集成（可选）

GitHub Actions 配置

文件：.github/workflows/lint.yml

name: Code Quality Check

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Set up Go
        uses: actions/setup-go@v4
        with:
          go-version: '1.25'
      
      - name: Run Code Quality Checks
        run: bash scripts/check-all.sh

本地使用

开发者可以在本地运行检查：

# 运行所有检查
bash scripts/check-all.sh

# 运行单项检查
bash scripts/check-service-errors.sh
bash scripts/check-comment-paths.sh

Pre-commit Hook（可选）

可以配置 Git pre-commit hook 在提交前自动检查：

文件：.git/hooks/pre-commit

#!/bin/bash

echo "运行代码规范检查..."
bash scripts/check-all.sh

if [ $? -ne 0 ]; then
    echo ""
    echo "代码规范检查失败，提交已取消"
    echo "请修复上述问题后重新提交"
    exit 1
fi

echo "代码规范检查通过，继续提交..."

扩展性设计

添加新的检查规则

添加新的检查规则的步骤：

1. 创建检查脚本：scripts/check-{name}.sh

   #!/bin/bash
   echo "🔍 检查 [检查项名称]..."
   
   # 检查逻辑
   VIOLATIONS=$(检查命令)
   
   if [ -n "$VIOLATIONS" ]; then
       echo "❌ 发现违规"
       echo "$VIOLATIONS"
       exit 1
   fi
   
   echo "✅ 检查通过"
   

2. 添加执行权限：

   chmod +x scripts/check-{name}.sh
   

3. 集成到统一脚本： 在 scripts/check-all.sh 中添加：

   bash scripts/check-{name}.sh
   

4. 测试脚本：

   # 测试通过场景
   bash scripts/check-{name}.sh  # 应返回退出码 0
   
   # 测试失败场景（制造违规）
   # 验证能检测到违规并返回退出码 1
   

5. 更新文档： 在 README.md 和本规范文档中添加新检查的说明

检查规则示例

以下是一些可能添加的检查规则：

检查项	脚本名称	检查内容
常量硬编码	check-constants.sh	检查代码中是否有硬编码的 magic numbers 和字符串
日志规范	check-logging.sh	检查日志是否使用结构化字段（zap.String、zap.Int 等）
TODO 标记	check-todos.sh	统计代码中的 TODO 数量，超过阈值时警告
导入路径	check-imports.sh	检查是否使用了禁止的包（如 fmt.Println）
测试覆盖率	check-coverage.sh	检查测试覆盖率是否达标

性能考虑

检查耗时

所有检查脚本应在合理时间内完成：

• 单项检查：< 10 秒
• 统一检查：< 30 秒

优化建议

1. 并行执行：多个独立检查可以并行运行
2. 缓存结果：避免重复扫描相同文件
3. 增量检查：仅检查变更的文件（CI 场景）

并行执行示例

#!/bin/bash
# scripts/check-all-parallel.sh

# 在后台运行检查
bash scripts/check-service-errors.sh &
PID1=$!

bash scripts/check-comment-paths.sh &
PID2=$!

# 等待所有检查完成
wait $PID1
RESULT1=$?

wait $PID2
RESULT2=$?

# 检查结果
if [ $RESULT1 -ne 0 ] || [ $RESULT2 -ne 0 ]; then
    echo "❌ 至少有一项检查失败"
    exit 1
fi

echo "✅ 所有检查通过"

测试策略

脚本测试清单

每个检查脚本应测试以下场景：

1. 通过场景：无违规时返回 0
2. 失败场景：有违规时返回 1 并输出错误
3. 白名单机制：白名单注释生效（如适用）
4. 边界情况：空目录、特殊字符等

测试示例

# 测试 Service 层错误检查

# 1. 通过场景
bash scripts/check-service-errors.sh
echo "退出码: $?"  # 应为 0

# 2. 失败场景
echo 'return fmt.Errorf("test")' >> internal/service/test_violation.go
bash scripts/check-service-errors.sh
echo "退出码: $?"  # 应为 1
rm internal/service/test_violation.go

# 3. 白名单机制
echo 'return fmt.Errorf("debug") // whitelist:' >> internal/service/test_whitelist.go
bash scripts/check-service-errors.sh
echo "退出码: $?"  # 应为 0
rm internal/service/test_whitelist.go

维护指南

定期维护

• 每月审查：检查是否有新的规范需要自动化检查
• 每季度更新：根据团队反馈优化错误消息和修复建议
• 每半年评估：评估检查脚本的性能和有效性

处理误报

如果检查脚本产生误报：

1. 评估规则：检查规则是否过于严格
2. 白名单机制：考虑添加白名单支持
3. 改进检测：优化正则表达式或检查逻辑
4. 文档说明：在规范文档中说明特殊场景

版本控制

检查脚本应纳入版本控制：

• 脚本修改需要通过 Code Review
• 重大变更需要更新文档
• 保持脚本向后兼容（或提供迁移指南）

总结

本 CI 检查规范定义了：

1. 检查脚本列表：Service 层错误检查、注释路径检查、统一检查
2. 脚本规范：输出格式、错误消息、Shell 兼容性
3. CI 集成：GitHub Actions、本地使用、Pre-commit Hook
4. 扩展性设计：添加新规则的步骤和示例
5. 性能优化：并行执行、增量检查
6. 测试策略：通过/失败/白名单/边界情况
7. 维护指南：定期审查、处理误报、版本控制

这些脚本确保代码质量和规范一致性，支持自动化检查和团队协作。