api-interface-design

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&#x3C;Page&#x3C;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 注解

api-interface-design

Safety Notice

Copy this and send it to your AI assistant to learn

Source Transparency

Related Skills

agent-module-architecture

frontend-vue-development

design-patterns