API 接口设计

Name: api-interface-design
Rating: 92
Author: TencentBlueKing

Quick Reference

code

路径格式：/{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 = 无效参数

最简示例

kotlin

@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	服务器内部错误

错误码规范

code

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

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

抛出错误

kotlin

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

统一返回格式

kotlin

// 成功返回
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`

接口版本管理

kotlin

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

Checklist

设计 API 前确认：

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