majiayu000 ginx-skill
本 skill 提供基于 ginx 框架的 HTTP API 开发约定，包括接口定义、中间件、错误码、国际化字符串等规范。当你在本项目中新增或修改 HTTP API、中间件、错误码、I18N、OpenAPI 生成等功能时，使用本 skill 约束自己的行为。
快速开始
当用户需要创建新的 HTTP 接口时：
- 实现
HandleOperator接口（包含Path(),Method(),Validate(),Output()方法） - 一个接口一个文件，文件名与结构体名保持一致
- 使用
intag 声明参数类型（query、path、body、form 等） - 使用
validatetag 进行参数校验 - 错误返回使用
statuserror库定义的错误码
详细约定请参考 references/api.md。
何时使用本 skill
在以下场景中自动启用本 skill：
- 用户在
apis/或apis/middleware/目录下新增或修改接口 - 用户提到"添加 API"、"路由注册"、"中间件"、"错误码"、"国际化字符串"等相关内容
- 用户要求"按项目原有风格"写 HTTP 接口、路由组或中间件
- 用户使用 ginx 框架时，必须遵守框架约定
核心原则
优先使用 ginx 模式，不要回退到原生 gin：
- 使用
ginx的接口/路由/中间件模式，而不是裸ginhandler - 使用
Validate+Output的职责分离 - 错误码定义：首先遵循当前项目的错误码规范，如果找不到相关规范，则使用 ginx 定义的
statuserror标准（使用@errZH/@errEN注释和toolx gen error生成），不要直接使用error.New - 国际化字符串定义：首先遵循当前项目的 i18n 规范，如果找不到相关规范，则使用 ginx 定义的 i18n 标准（使用
@i18nZH/@i18nEN注释和toolx gen i18n生成），不要直接使用i18n.New - 代码示例应复用项目中的结构和命名方式，与现有代码保持风格统一
只有在现有模式无法覆盖需求时，才说明原因并给出兼容性较好的变更方案。
使用步骤
1. 理解框架约定
在编写代码前，先阅读 references 目录下的文档：
- references/api.md：HTTP API 接口定义、路由组、中间件、参数绑定、ContentType、Swagger 注释等约定
- references/error.md：错误码定义、生成、参数注入、错误列表、国际化字符串定义、生成等约定
2. 回答用户时的约束
回答中应显式体现：
- ✅ 使用
ginx的接口/路由/中间件模式，而不是裸gin - ✅ 使用 实现完整的接口定义，
Validate+Output的职责分离 - ✅ 使用
statuserror库定义错误码 - ✅ 使用
i18n生成工具定义国际化字符串 - ✅ 一个接口一个文件的组织方式
只有在现有模式无法覆盖需求时，才说明原因并给出兼容性较好的变更方案。
常见问题
Q: 什么时候需要使用原生 gin 而不是 ginx？
A: 只有在现有 ginx 模式无法覆盖需求时（如工具链限制、临时调试等），才说明原因并使用原生 gin。一般情况下应优先使用 ginx 模式。
Q: 如何确保代码符合项目风格？
A: 参考项目中现有的 API 实现，保持命名方式、代码结构和注释风格一致。。
Q: 错误码和国际化字符串必须一起定义吗？
A: 是的，错误码定义时需要同时提供中英文描述（@errZH 和 @errEN），然后执行生成命令即完成i18n注册。