ApiHug Lint

用 ApiHug Lint 检查契约描述、元数据完整性以及其他设计质量违规项。

ApiHug Lint 用来检查契约是否足够清晰、完整，能否支撑后续生成、评审和 AI 使用场景。

它是什么

Lint 是一层规则驱动的契约质量检查，重点不在代码格式，而在 API 描述与建模质量。

为什么重要

生成式系统会放大弱契约的代价。描述缺失、字段命名含糊、问题提示太薄，最终都会同时伤害开发体验和 AI 可用性。

它如何融入整体流程

1. 启用对应版本

先使用包含 lint 能力的 ApiHug SDK，再在项目根目录加入 .apihuglint.properties。

2. 配置规则

常见配置项包括：

属性	作用说明
`violation.limit`	违规超过阈值时让构建失败
`service.description.length`	service 描述最小长度
`service.api.description.length`	operation 描述最小长度
`service.api.questions.size`	prompt questions 最小数量
`message.field.description.length`	字段描述最小长度
`entity.table.explicit`	是否要求显式表名
`entity.column.explicit`	是否要求显式列名

3. 查看输出

proto 模块构建成功后，报告会输出到：

{PROTO_MODULE}/build/reports/api-lint/

其中包括：

report.html，适合人工查看
report.json，适合自动化与 CI 接入

JSON 结果示例

JSON

[
  {
    "proto": "com/apihug/sample/proto/api/demo001/api.proto",
    "kind": "Service",
    "target": "VIPService#GetMeSth",
    "rule": "Service method description too short",
    "description": "Given [Get me something] expect >= 20"
  }
]

下一步

把 lint 放进 proto 构建流水线
需要人工补充判断时，再结合 Proto Review