API 接口设计 Quick Reference 路径格式：/{scope}/{resource}/{resourceId}/{subResource} 路径前缀：/user/(Web) | /service/(内部) | /build/(Agent) | /open/(外部) 返回格式：Result { status, message, data } 分页格式：Page { 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( val status: Int, // 状态码 val message: String?, // 提示信息 val data: T? // 返回数据 )

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

请求/响应对象命名类型命名模式示例创建请求 [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 包装分页接口使用 Page 错误码符合规范格式添加完整的 Swagger 注解

api-interface-design

安装