api-generator

# 接口设计生成指南 ## 设计范围 本 Skill 负责生成接口设计文档，不生成具体代码实现： | 输出 | 说明 | |------|------| | URL 设计 | RESTful 路径、HTTP 方法 | | 请求参数 | Path/Query/Body 参数定义 | | 响应结构 | 成功/失败返回格式 | | 权限标识 | 接口所需权限点 | | Swagger 注解 | `@Tag`、`@Operation` 等 | | 前端接口定义 | `lm api` 生成的前端 API 封装，存放于 `src/api/module/xxx/index.ts` | 自动 | ## URL 设计规范 ### 管理端接口 ``` /admin/{biz}/{action} 示例： POST /admin/announcement/create # 创建公告 POST /admin/announcement/update # 更新公告 GET /admin/announcement/delete # 删除公告 GET /admin/announcement/get # 查询详情 POST /admin/announcement/page # 分页查询 ``` ### 用户端（小程序/App）接口 ``` /app/{biz}/{action} 示例： POST /app/announcement/list # 列表查询（用户端） GET /app/announcement/detail # 详情查询（用户端） ``` ### HTTP 方法规范 | 方法 | 用途 | |------|------| | `GET` | 查询、删除（简单操作） | | `POST` | 创建、更新、复杂查询（分页） | | `PUT` | 全量更新（少用） | | `DELETE` | 删除（少用，项目多用 GET） | ## 请求参数规范 ### Path 参数 ```java @GetMapping("/get") public CommonResult<AnnouncementRespVO> get(@RequestParam("id") Long id) ``` ### Body 参数（创建/更新） ```java @PostMapping("/create") public CommonResult<Long> create(@Valid @RequestBody AnnouncementCreateReqVO reqVO) ``` ### 分页查询 ```java @PostMapping("/page") public CommonResult<PageResult<AnnouncementRespVO>> page(@RequestBody AnnouncementPageReqVO reqVO) ``` ## 响应结构规范 ### 成功响应 ```json { "code": 0, "data": { ... }, "msg": "" } ``` ### 分页响应 ```json { "code": 0, "data": { "list": [ ... ], "total": 100 }, "msg": "" } ``` ### 失败响应 ```json { "code": 1_100_007_000, "data": null, "msg": "公告不存在" } ``` ## 接口设计模板 ``` ## 公告管理接口 ### 1. 创建公告 - **URL**: POST /admin/announcement/create - **权限**: app:announcement:create - **请求**: AnnouncementCreateReqVO - title (string, required): 公告标题 - content (string, required): 公告内容 - type (int): 公告类型：1通知 2公告 - **响应**: CommonResult<Long> (公告ID) ### 2. 更新公告 - **URL**: POST /admin/announcement/update - **权限**: app:announcement:update - **请求**: AnnouncementUpdateReqVO - id (long, required): 公告编号 - title (string, required): 公告标题 - content (string, required): 公告内容 - type (int): 公告类型 - status (int): 状态 - **响应**: CommonResult<Boolean> ### 3. 删除公告 - **URL**: GET /admin/announcement/delete - **权限**: app:announcement:delete - **请求**: id (long, query) - **响应**: CommonResult<Boolean> ### 4. 查询详情 - **URL**: GET /admin/announcement/get - **权限**: app:announcement:query - **请求**: id (long, query) - **响应**: CommonResult<AnnouncementRespVO> ### 5. 分页查询 - **URL**: POST /admin/announcement/page - **权限**: app:announcement:query - **请求**: AnnouncementPageReqVO - pageNo (int): 页码 - pageSize (int): 每页条数 - title (string): 标题（模糊查询） - type (int): 类型 - status (int): 状态 - **响应**: CommonResult<PageResult<AnnouncementRespVO>> ``` ## 配合 CLI 工具 设计接口前，建议先了解已有的 DO/Mapper（由开发者自行创建维护），确保接口定义与数据模型一致。 ### CLI 安装与使用 ```bash npm config set registry https://registry.npmmirror.com/ npm config set @lingman:registry=https://git.lingman.tech:8081/repository/npm_hosted/ npm install @lingman/cli -g ``` 项目根目录需配置 `lingman.config.json`（通过 `lm init java` 初始化）： ```json { "lang": "java", "template": "", "db": { "url": "jdbc:postgresql://<host>:<port>/<database>", "username": "<username>", "password": "<password>", "hasBase": false }, "fileOverride": false } ``` - `fileOverride`：控制是否覆盖已存在的文件。`true` — 覆盖更新；`false` — 不覆盖（默认） DO/Mapper 由开发者自行创建维护（`lm mapper` 可选但**不推荐日常使用**，详见 crud-generator）；在**前端工程根目录**下运行 `lm api` 可根据 Swagger 生成前端接口定义。 > **重要**：`lm api` 必须在前端工程根目录中运行，不能在其他子目录中执行。 ## 参考文档 | 场景 | 参考文档 | |------|----------| | 接口设计示例 | [api-examples.md](references/api-examples.md) | | 框架规范 | [framework.md](../lingman-core/framework.md) | | 代码模板 | [code-template.md](../crud-generator/references/code-template.md) |