ApiHug 2.0 LLM 优化规范

更新于 2026-01-03

概览

ApiHug 2.0 面向 LLM（大语言模型）驱动的开发工作流进行优化，核心目标是让契约、生成、实现和评审处在同一套可理解的上下文中。对应的三个重点是：

1. 简化协议类型，降低模型理解负担。
2. 统一插件与模块上下文，减少工程结构噪音。
3. 用 Spec-Driven 文档把 API、Domain、Constant、Mock 与历史兼容规范说清楚。

1. 面向 LLM 的设计原则

1.1 协议类型简化

背景：像 google.protobuf.Int32Value 这样的 wrapper 类型会增加 AI 和人类同时理解 proto 的成本，也更容易让生成结果出现不稳定的样式。

推荐做法：尽量使用原生 proto3 基础类型。

// 不推荐
message OldRequest {
  google.protobuf.Int32Value user_id = 1;
  hope.common.BoolType is_active = 2;
}

// 推荐
message NewRequest {
  int32 user_id = 1;
  bool is_active = 2;
}

1.2 统一插件上下文

版本要求：SDK >= 2.1.0-RELEASE

ApiHug 2.0 合并了过去分散的插件和模块结构：

• 废弃独立插件：com.apihug.wire、com.apihug.stub
• 废弃 proto 模块 + app 模块的拆分默认模式
• 统一为 com.apihug.hope
• 默认把主要代码放回一个 app 模块里

这带来的直接收益是：

• IDE 可以建立更连续的上下文
• AI 更容易理解项目结构
• 构建配置更少，生成路径更清晰

gradle/libs.versions.toml

[versions]
apihugVersion = "2.1.0-RELEASE"

[plugins]
hope = { id = "com.apihug.hope", version.ref = "apihugVersion" }
hope-repl = { id = "com.apihug.repl", version.ref = "apihugVersion" }

build.gradle

plugins {
    id "java"
    alias(libs.plugins.spring.boot)
    alias(libs.plugins.spring.dependency)
    alias(libs.plugins.hope)
}

hope {
    debug = false
    verbose = false

    // 可选能力
    // enableFrontVue = true
    // enableMcp = true
}

2. Spec-Driven 规范体系

ApiHug 基于 Protocol Buffers 扩展定义了一组核心规范。当前建议关注四个活跃规范，另保留一个历史兼容规范供旧项目审计使用。

2.1 核心规范文档

2.2 分层关系

• api/ 层负责 REST API、请求响应 DTO 与 OpenAPI 表达。
• domain/ 层负责实体、表结构和数据库语义。
• infra/ 层负责错误码、常量、共享枚举等基础定义。

分层原则

• API 层和 Domain 层都可以引用 Infra 层。
• 同一层内部允许共享引用。
• API 层和 Domain 层之间禁止直接跨层引用。

3. BMAD AI 工作流

ApiHug 提供了一套围绕规范驱动开发的 BMAD 工作流，用来把需求、契约、实现和评审串起来。

前置条件：安装 ApiHug REPL

更多说明：

• ApiHug BMAD 文档
• BMAD Method

4. 最佳实践

4.1 面向 LLM 的 proto 编写建议

1. 优先使用基础类型，避免 wrapper 类型。
2. 让命名保持清晰稳定：消息用 PascalCase，字段用 snake_case。
3. 优先用 description 等结构化字段表达说明，而不是把关键信息散落在普通注释里。
4. 严格遵守 API / Domain / Infra 分层。

4.2 版本迁移检查清单

升级到 2.1.0+ 时，建议依次检查：

• 从 gradle/libs.versions.toml 移除 hope-wire 与 hope-stub
• 在 build.gradle 中改为 alias(libs.plugins.hope)
• 把旧的 proto 模块能力合并到当前 app 模块
• 排查并替换历史 wrapper 类型
• 运行 ./gradlew clean build 验证升级结果

参考资源

工具文档

1. ApiHug REPL - 命令行工具
2. ApiHug BMAD - AI 开发方法

规范文档

1. API 指令规范
2. 数据库指令规范
3. 常量与枚举规范
4. Mock 数据规范
5. 版本变更规范

外部资源

• BMAD Method GitHub
• Protocol Buffers 官方文档
• OpenAPI 规范