API 接口设计 Skill | Agent Skills

API 接口设计

Quick Reference

路径格式：/{scope}/{resource}/{resourceId}/{subResource}
路径前缀：/user/(Web) | /service/(内部) | /build/(Agent) | /open/(外部)
返回格式：Result<T> { status, message, data }
分页格式：Page<T> { count, page, pageSize, totalPages, records }
错误码格式：21(平台)01(服务)001(业务码) → 如 2100013 = 无效参数

最简示例

@Tag(name = "USER_PIPELINE", description = "用户-流水线资源")
@Path("/user/pipelines")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
interface UserPipelineResource {

    @Operation(summary = "获取流水线列表")
    @GET
    @Path("/")
    fun list(
        @Parameter(description = "用户ID", required = true)
        @HeaderParam(AUTH_HEADER_USER_ID) userId: String,
        @Parameter(description = "项目ID", required = true)
        @PathParam("projectId") projectId: String,
        @QueryParam("page") page: Int?,
        @QueryParam("pageSize") pageSize: Int?
    ): Result<Page<PipelineInfo>>
}

When to Use

设计 RESTful API 接口
定义 Resource 类
需要了解错误码规范
设计请求/响应数据结构

When NOT to Use

实现业务逻辑 → 使用 01-backend-microservice-development
参数校验规则 → 使用 common-technical-practices (reference/4-parameter-validation.md)

路径命名规范

| 路径前缀 | 用途 | 调用方 | |---------|------|--------| | /user/ | 用户态接口 | 前端 Web | | /service/ | 服务间调用 | 其他微服务 | | /build/ | 构建相关 | Agent/Worker | | /open/ | 对外开放 | 第三方系统 |

HTTP 状态码使用

| 状态码 | 场景 | |--------|------| | 200 | 请求成功 | | 201 | 创建成功 | | 400 | 请求参数错误 | | 401 | 未认证 | | 403 | 无权限 | | 404 | 资源不存在 | | 500 | 服务器内部错误 |

错误码规范

21(平台)01(服务)001(业务码)

平台：21 = BK-CI
服务：01 = 通用, 02 = process, 03 = project ...
业务码：001-999 = 具体错误

抛出错误

throw ErrorCodeException(
    statusCode = 400,
    errorCode = "2100013",
    defaultMessage = "无效参数",
    params = arrayOf(paramName)
)

统一返回格式

// 成功返回
data class Result<T>(
    val status: Int,      // 状态码
    val message: String?, // 提示信息
    val data: T?          // 返回数据
)

// 分页返回
data class Page<T>(
    val count: Long,      // 总数
    val page: Int,        // 当前页
    val pageSize: Int,    // 每页数量
    val totalPages: Int,  // 总页数
    val records: List<T>  // 数据列表
)

请求/响应对象命名

| 类型 | 命名模式 | 示例 | |------|---------|------| | 创建请求 | [Resource]CreateRequest | PipelineCreateRequest | | 更新请求 | [Resource]UpdateRequest | PipelineUpdateRequest | | 详情响应 | [Resource]Info | PipelineInfo | | 列表项 | [Resource]Summary | PipelineSummary |

接口版本管理

@Path("/v3/user/pipelines")  // v3 版本
@Path("/v4/user/pipelines")  // v4 版本

Checklist

设计 API 前确认：

[ ] 路径前缀符合调用方场景
[ ] 使用正确的 HTTP 方法
[ ] 返回值使用 Result<T> 包装
[ ] 分页接口使用 Page<T>
[ ] 错误码符合规范格式
[ ] 添加完整的 Swagger 注解

Agent Skills: API 接口设计

Install this agent skill to your local

Skill Files