AI Coding 最佳实践

AI Coding Best Practices

引言

经过一年的 AI 编码实践，HotelByte 项目从最初的”复制粘贴式编程”演进到完整的 AI 辅助开发体系。本文将总结我们的最佳实践，包括效率提升数据、代码质量标准、前瞻性布局的核心创新，以及未来规划。

效率提升数据

开发效率对比

指标	传统开发	DeepSeek 时代	Claude Code + OpenSpec	提升幅度
功能开发时间	5-7 天	3-5 天	1-2 天	3.5x
Bug 修复时间	2-4 小时	1-2 小时	30-60 分钟	3x
代码审查时间	1-2 小时	1-1.5 小时	30-45 分钟	2x
测试编写时间	2-3 小时	1.5-2 小时	30-60 分钟	3x
文档编写时间	1-2 小时	1-1.5 小时	5-10 分钟	10x

成本分析

成本类型	传统开发	AI 编码	节省
开发人力成本	$10,000/月	$5,000/月	50%
AI 工具成本	$0	$300/月	-$300
培训成本	$2,000	$1,000	50%
Bug 修复成本	$3,000/月	$500/月	83%
总成本	$15,000/月	$6,800/月	55%

质量指标

指标	传统开发	AI 编码	改进
测试覆盖率	40-50%	65-75%	+30%
代码审查通过率	60%	85%	+25%
线上 Bug 率	15%	5%	-67%
文档更新及时性	30%	95%	+217%
代码规范符合度	70%	95%	+36%

前瞻性布局：代码即文档

核心理念

“代码即文档”不是简单的”代码包含注释”，而是通过元数据驱动，实现代码、文档、测试、路由的全自动同步。

httpdispatcher + make doc 的创新

在 HotelByte 项目中，我们构建了一个独特的”代码即文档”系统：

┌─────────────────────────────────────────────────────────────┐
│                     开发者写代码                              │
│  ┌──────────────┬──────────────┬──────────────┐          │
│  │  业务逻辑     │  元数据注释    │  类型定义     │          │
│  └──────────────┴──────────────┴──────────────┘          │
└─────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│              AST 解析（build/api/asthelper/）                │
│  ┌──────────────┬──────────────┬──────────────┐          │
│  │  comment.go  │ method_meta  │ visibility_  │          │
│  │  注释提取    │  元数据提取   │  control.go  │          │
│  └──────────────┴──────────────┴──────────────┘          │
└─────────────────────────────────────────────────────────────┘
                           ↓
        ┌──────────────────┴──────────────────┐
        ↓                                      ↓
┌──────────────────────┐        ┌──────────────────────┐
│   httpdispatcher     │        │    make doc         │
│  路由绑定 + 治理      │        │   文档生成           │
└──────────────────────┘        └──────────────────────┘
        ↓                                      ↓
┌──────────────────────┐        ┌──────────────────────┐
│  运行时路由表         │        │  OpenAPI 文档        │
│  参数解析             │        │  公开/内部版本       │
│  限流配置             │        │  多语言支持          │
│  缓存配置             │        │  SDK 生成            │
└──────────────────────┘        └──────────────────────┘

元数据注释系统

1. 类型可见性控制

//apidoc:public,zh:OrderStatus_Submitted,OrderStatus_Confirmed
type OrderStatus int

const (
    OrderStatus_Submitted OrderStatus = iota // 已提交
    OrderStatus_Confirming                  // 确认中
    OrderStatus_Confirmed                   // 已确认
    OrderStatus_Cancelled                   // 已取消
    OrderStatus_Refunded                    // 已退款
    OrderStatus_Failed                      // 失败
)

效果：

公开文档（Public API）：只显示 Submitted、Confirmed
内部文档（Internal）：显示所有状态
多语言支持：自动生成中英文文档

2. 方法元数据

// @jwt
// @permission:order:read
// @tags:order,booking
// @cache:ttl=600,userLevel=true
// @param:orderID string "订单ID"
// @param:includeDetails bool "是否包含详情"
func (s *OrderService) GetOrder(ctx context.Context, req *GetOrderRequest) (*GetOrderResponse, error) {
    // 业务逻辑
}

httpdispatcher 自动使用：

✅ JWT 认证
✅ 权限检查（order:read）
✅ API 标签
✅ 缓存配置（TTL=600s，用户级缓存）
✅ 参数解析和验证

3. 字段可见性

type OrderResponse struct {
    OrderID      string `json:"orderId" apidoc:"public"`
    Status       string `json:"status" apidoc:"public"`
    TotalPrice   int64  `json:"totalPrice" apidoc:"public"`
    InternalCode string `json:"internalCode" apidoc:"internal"`
    DebugInfo    string `json:"debugInfo" apidoc:"hidden"`
}

效果：

公开文档：只显示 OrderID、Status、TotalPrice
内部文档：额外显示 InternalCode
完全隐藏：DebugInfo 不在任何文档中

文档生成流程

命令使用

# 生成所有文档
make doc

# 只生成公开文档
make doc-public

# 只生成内部文档
make doc-internal

# 上传到文档服务器
make doc-upload

实际输出

公开 API 文档（docs/public/openapi.yaml）：

openapi: 3.0.0
info:
  title: HotelByte Public API
  version: 1.0.0
paths:
  /order/{orderId}:
    get:
      summary: 获取订单信息
      tags:
        - order
        - booking
      security:
        - jwt: []
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  orderId:
                    type: string
                    description: 订单ID
                  status:
                    type: string
                    description: 订单状态
                    enum:
                      - submitted
                      - confirmed
                  totalPrice:
                    type: integer
                    description: 总价格（fils）

内部 API 文档（docs/internal/openapi.yaml）：

openapi: 3.0.0
info:
  title: HotelByte Internal API
  version: 1.0.0
paths:
  /order/{orderId}:
    get:
      summary: 获取订单信息（内部）
      tags:
        - order
        - booking
      security:
        - jwt: []
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  orderId:
                    type: string
                  status:
                    type: string
                    enum:
                      - submitted
                      - confirming
                      - confirmed
                      - cancelled
                      - refunded
                      - failed
                  totalPrice:
                    type: integer
                  internalCode:
                    type: string
                    description: 内部错误码

对 AI 编码的影响

1. 减少样板代码

之前（手动编写文档）：

// 业务代码
func (s *OrderService) GetOrder(...) {...}

// 文档代码（手动维护）
var orderDocs = []api.Doc{
    {
        Path: "/order/{orderId}",
        Method: "GET",
        Summary: "获取订单信息",
        Parameters: []api.Param{
            {Name: "orderId", Type: "string", Required: true},
            {Name: "includeDetails", Type: "boolean"},
        },
        Responses: []api.Response{
            {Code: 200, Description: "成功"},
        },
    },
}

现在（自动生成）：

// 只需添加元数据注释
// @jwt
// @permission:order:read
// @tags:order
// @param:orderID string "订单ID"
func (s *OrderService) GetOrder(ctx context.Context, req *GetOrderRequest) (*GetOrderResponse, error) {
    // 业务逻辑
}

// 文档自动生成，零维护成本

减少代码量： 80%

2. 一致性保证

问题场景： API 接口变更

场景	手动维护	自动生成
添加参数	修改代码 + 修改文档（经常忘记）	只修改代码，文档自动更新
删除字段	修改代码 + 修改文档	只修改代码，文档自动更新
修改类型	修改代码 + 修改文档	只修改代码，文档自动更新
修改验证规则	修改代码 + 修改文档 + 修改路由配置	只修改代码，其他自动更新

一致性保证： 100%

3. 可观测性提升

httpdispatcher 自动暴露路由信息：

# 查看所有路由
curl http://localhost:8080/_debug/routes

# 输出：
[
  {
    "path": "/order/{orderId}",
    "method": "GET",
    "serviceName": "OrderService",
    "methodName": "GetOrder",
    "authMethod": "jwt",
    "permissions": ["order:read"],
    "cache": {"ttl": 600, "userLevel": true},
    "rateLimit": {"qps": 100, "burst": 200}
  }
]

便于：

✅ 调试路由问题
✅ 监控 API 性能
✅ 分析权限配置
✅ 审查缓存策略

4. 多语言支持

通过语言标签实现自动翻译：

//apidoc:public,zh:OrderStatus_Submitted,OrderStatus_Confirmed
type OrderStatus int

生成的文档：

中文版：

{
  "status": {
    "type": "string",
    "description": "订单状态",
    "enum": ["submitted", "confirmed"],
    "x-displayNames": {
      "zh": {
        "submitted": "已提交",
        "confirmed": "已确认"
      }
    }
  }
}

英文版：

{
  "status": {
    "type": "string",
    "description": "Order status",
    "enum": ["submitted", "confirmed"],
    "x-displayNames": {
      "en": {
        "submitted": "Submitted",
        "confirmed": "Confirmed"
      }
    }
  }
}

5. SDK 自动生成

基于 OpenAPI 文档，自动生成多语言 SDK：

# 生成 Go SDK
make sdk-go

# 生成 Python SDK
make sdk-python

# 生成 JavaScript SDK
make sdk-js

实际效果数据

指标	手动维护	代码即文档	提升
文档维护时间	4-6 小时/周	0 小时/周	100%
文档准确性	60-70%	100%	+40%
API 变更同步延迟	2-3 天	实时	即时
多语言文档维护	8-10 小时/周	0 小时/周	100%
SDK 生成时间	手动 2-3 天	自动 5 分钟	99%

测试覆盖率标准

强制检查

PR 强制检查： 增量代码测试覆盖率必须 ≥ 50%

# .github/workflows/test.yml
name: Test Coverage Check

on: [pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Run tests
        run: make test-coverage
      - name: Check coverage threshold
        run: |
          COVERAGE=$(make get-coverage)
          if [ $(echo "$COVERAGE < 50" | bc) -eq 1 ]; then
            echo "Coverage $COVERAGE% is below 50%"
            exit 1
          fi

分层覆盖率目标

层级	覆盖率目标	原因
domain/	100%	核心业务逻辑，必须完整测试
mysql/ (DAO)	80%+	数据库操作，大部分场景需要测试
service/	70%+	业务服务，核心流程需要测试
convert/	90%+	转换函数，简单但需要完整覆盖
protocol/	不要求	纯数据结构，无需测试

实际覆盖率数据

hotel/user/domain/       100% ✅
hotel/user/mysql/         85% ✅
hotel/user/service/       78% ✅
hotel/order/domain/       100% ✅
hotel/order/mysql/         82% ✅
hotel/order/service/       75% ✅
hotel/trade/domain/       100% ✅
hotel/trade/mysql/         79% ✅
hotel/trade/service/       72% ✅

整体覆盖率: 76% ✅
增量覆盖率: 62% ✅ (目标: 50%)

代码质量标准

编码规范（零容忍）

参考 .github/code_review_rules.md，强制执行：

1. 日志规范

// ❌ 错误：使用 fmt.Printf
fmt.Printf("User logged in: %s\n", username)

// ✅ 正确：使用统一日志
log.Info("User logged in", log.Field("username", username))

2. JSON 处理

// ❌ 错误：使用 json.Marshal
data, err := json.Marshal(user)

// ✅ 正确：使用 utils.ToJSON
data, err := utils.ToJSON(user)

3. ID 生成

// ❌ 错误：手动生成 ID
userID := time.Now().Unix()

// ✅ 正确：使用 idgen
userID := idgen.GenID()

4. 时间字段

// ❌ 错误：DAO 层设置时间
user.CreatedAt = time.Now()
dao.Update(user)

// ✅ 正确：由数据库维护
user.Status = "active"
dao.Update(user) // create_time/update_time 自动更新

代码审查流程

1. 自动检查

# CI 检查清单
- [ ] 代码格式化（gofmt）
- [ ] 代码检查（golangci-lint）
- [ ] 测试覆盖率（≥50%）
- [ ] 单元测试（全部通过）
- [ ] E2E 测试（核心场景）
- [ ] 文档生成（make doc）

2. 人工审查

审查要点：

✅ 业务逻辑正确性
✅ 性能影响评估
✅ 安全性检查
✅ 错误处理完整性
✅ 代码可读性
✅ 测试充分性

3. AI 辅助审查

使用 KIMI2 进行自动审查：

# 提交 PR 后自动触发
code-review --model kimi2 --pr $PR_NUMBER

# 输出：
# ✅ 发现 3 个潜在问题
# ✅ 建议 2 处优化
# ✅ 标注 1 个安全隐患

AI 编码流程

完整流程图

┌─────────────────────────────────────────────────────────────┐
│  1. 需求收集                                                │
│     产品经理 → OpenSpec 提案                               │
└─────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│  2. 规格定义                                                │
│     AI（GLM4.6） → proposal.md + tasks.md + spec deltas   │
└─────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│  3. 提案评审                                                │
│     团队评审 → 批准/修改/拒绝                                │
└─────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│  4. 代码实施                                                │
│     AI（DeepSeek/GLM4.6）→ domain → protocol → mysql →    │
│     service + 测试                                          │
└─────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│  5. 代码审查                                                │
│     AI（KIMI2） + 人工 → 发现问题/建议优化                   │
└─────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│  6. 文档生成                                                │
│     make doc → OpenAPI 文档（公开/内部）                   │
└─────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│  7. 测试验证                                                │
│     单元测试 + E2E 测试 → 覆盖率检查 → 通过/失败            │
└─────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│  8. 部署上线                                                │
│     部署脚本 → 监控 → 灰度 → 全量                           │
└─────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│  9. 归档记录                                                │
│     openspec archive → 更新 specs/ → 知识沉淀                │
└─────────────────────────────────────────────────────────────┘

典型案例：订单状态回调功能

时间线

阶段	耗时	AI 模型	输出
1. 需求分析	30 分钟	GLM4.6	OpenSpec 提案
2. 技术设计	1 小时	MiniMax M2	design.md
3. 代码生成	2 小时	GLM4.6	完整代码 + 测试
4. 代码审查	30 分钟	KIMI2	审查报告
5. 文档生成	5 分钟	自动	OpenAPI 文档
6. 测试验证	1 小时	-	全部通过
7. 部署上线	30 分钟	-	成功

总耗时： 5.5 小时（之前：2-3 天）

成本： $2（AI 工具） + $50（人工） = $52（之前：$500）

教训与经验

关键教训

1. 上下文比代码更重要

错误做法：

用户：帮我写一个订单查询接口
AI：（生成通用代码，不符合项目规范）

正确做法：

用户：使用 .cursor/skills/supplier-onboarding 技能，为订单查询接口生成代码
AI：（理解项目规范，生成符合要求的代码）

2. 流程比工具更重要

错误做法：

依赖 AI "魔法"，没有规范流程
→ 代码质量不稳定
→ 团队成员使用方式不一致
→ 知识无法沉淀

正确做法：

建立 OpenSpec 工作流
→ 所有变更都有明确的规格
→ 流程一致，结果可预期
→ 知识沉淀在规格文件中

3. 测试是刚需，不是可选

错误做法：

AI 生成代码 → 手动测试一下 → 提交
→ 线上 Bug 频发
→ 维护成本高

正确做法：

AI 生成代码 + 测试 → 运行测试 → 覆盖率检查 → 提交
→ 线上 Bug 率降低 67%
→ 维护成本低

4. 质量不能妥协

错误做法：

为了速度，降低测试覆盖率要求
→ 短期快，长期慢
→ 技术债务累积

正确做法：

严格执行质量标准
→ 覆盖率 < 50% 不允许合并
→ 代码审查不通过不合并
→ 测试不通过不合并
→ 长期效率更高

最佳实践清单

开发前

阅读 openspec/AGENTS.md
检查是否有相关的 OpenSpec 变更
选择合适的 AI 模型
准备项目上下文

开发中

遵循 DDD 架构（domain → protocol → mysql → service）
添加元数据注释（httpdispatcher 兼容）
编写单元测试
编写 E2E 测试（核心场景）

开发后

运行 make test 检查单元测试
运行 make test-coverage 检查覆盖率
运行 make doc 生成文档
运行 AI 代码审查（KIMI2）
人工代码审查
提交 PR

上线后

监控线上指标
收集反馈
openspec archive 归档
更新文档和知识库

未来路线图

短期目标（1-3 个月）

中期目标（3-6 个月）

长期目标（6-12 个月）

总结

核心价值

效率提升 3.5x：从 5-7 天到 1-2 天
成本降低 55%：从 $15,000/月到 $6,800/月
质量提升 30%：测试覆盖率从 40-50% 到 65-75%
文档同步 100%：代码即文档，零维护成本

关键创新

OpenSpec 工作流：规格驱动开发，质量第一
多模型智能路由：成本优化，性能平衡
httpdispatcher + make doc：代码即文档，前瞻性布局
完整测试体系：覆盖率强制检查，质量保证

给读者的建议

从简单开始：不要一开始就追求完美，先建立基础流程
重视规范：流程和规范比工具更重要
持续优化：根据实际情况调整，不要僵化
知识沉淀：记录经验教训，持续改进

致谢

感谢所有参与 HotelByte 项目的团队成员，以及在 AI 编码实践中贡献和分享的开发者社区。

系列导航

相关资源：

AI Coding 最佳实践

引言

效率提升数据

开发效率对比

成本分析

质量指标

前瞻性布局：代码即文档

核心理念

httpdispatcher + make doc 的创新

元数据注释系统

1. 类型可见性控制

2. 方法元数据

3. 字段可见性

文档生成流程

命令使用

实际输出

对 AI 编码的影响

1. 减少样板代码

2. 一致性保证

3. 可观测性提升

4. 多语言支持

5. SDK 自动生成

实际效果数据

测试覆盖率标准

强制检查

分层覆盖率目标

实际覆盖率数据

代码质量标准

编码规范（零容忍）

1. 日志规范

2. JSON 处理

3. ID 生成

4. 时间字段

代码审查流程

1. 自动检查

2. 人工审查

3. AI 辅助审查

AI 编码流程

完整流程图

典型案例：订单状态回调功能

时间线

教训与经验

关键教训

1. 上下文比代码更重要

2. 流程比工具更重要

3. 测试是刚需，不是可选

4. 质量不能妥协

最佳实践清单

开发前

开发中

开发后

上线后

未来路线图

短期目标（1-3 个月）

中期目标（3-6 个月）

长期目标（6-12 个月）

总结

核心价值

关键创新

给读者的建议

致谢

系列导航

评论