后端微服务开发
Quick Reference
核心服务：process(流水线) | project(项目) | repository(代码库) | auth(权限) 四层架构：api-{service}(接口) → biz-{service}(业务+DAO) → boot-{service}(启动) → model-{service}(数据模型) 包命名：com.tencent.devops.<module> Resource 前缀：User*(Web) | Service*(内部) | Build*(Agent) | Open*(外部)
最简示例
// Resource 接口定义 @Tag(name = "USER_PIPELINE", description = "用户-流水线资源") @Path("/user/pipelines") @Produces(MediaType.APPLICATION_JSON) interface UserPipelineResource { @GET @Operation(summary = "获取流水线列表") fun list(@HeaderParam(AUTH_HEADER_USER_ID) userId: String): Result<List<PipelineInfo>> }
// Resource 实现（构造器注入） @RestResource class UserPipelineResourceImpl @Autowired constructor( private val pipelineService: PipelineService ) : UserPipelineResource
When to Use
-
创建新微服务或添加新 Resource
-
编写 Kotlin/Java 后端代码
-
设计服务间调用架构
-
需要了解项目分层规范
When NOT to Use
-
前端 Vue 开发 → 使用 04-frontend-vue-development
-
Agent Go 开发 → 使用 05-go-agent-development
-
数据库 DDL 编写 → 使用 database-design
四层分层架构
core/{service}/ ├── api-{service}/ # API接口定义层 - 对外暴露服务契约 ├── biz-{service}/ # 业务逻辑层 - 包含 Service、DAO ├── boot-{service}/ # Spring Boot启动层 - 独立部署单元 └── model-{service}/ # 数据模型层 - JOOQ 生成的数据库访问对象
16 个核心微服务
服务 职责
project 项目管理（所有模块基础依赖）
process 流水线编排与调度（核心服务）
repository 代码库管理
artifactory 制品库（对接 COS/S3）
store 研发商店（插件、模板）
environment 构建机/环境管理
dispatch 构建调度分发
auth 权限认证（RBAC）
ticket 凭证管理
log 构建日志
quality 质量红线
notify 通知服务
openapi 对外 API
metrics 度量服务
websocket WebSocket 服务
misc 杂项服务
Resource 命名规范
前缀 用途 路径前缀 示例
User*Resource
用户 Web 交互 /user/
UserPipelineResource
Service*Resource
服务间内部调用 /service/
ServiceBuildResource
Build*Resource
构建过程 Agent/Worker /build/
BuildArtifactoryResource
BuildAgent*Resource
第三方 Agent 专用 /buildAgent/
BuildAgentCredentialResource
Open*Resource
对外开放（OpenAPI） /open/
OpenPipelineTaskResource
Op*Resource
运营管理接口 /op/
OpProjectResource
注解使用标准
API 定义
@RestResource // REST 资源实现类 @Path("/user/artifactories") @GET / @POST / @PUT / @DELETE @Produces(MediaType.APPLICATION_JSON) @Consumes(MediaType.APPLICATION_JSON)
Swagger 文档
@Tag(name = "USER_ARTIFACTORY", description = "版本仓库-仓库资源") @Operation(summary = "根据元数据获取文件") @Parameter(description = "用户ID", required = true)
参数校验
@BkField(minLength = 1, maxLength = 128) @BkField(patternStyle = BkStyleEnum.CODE_STYLE)
方法命名约定
操作 命名前缀
查询 get* , query* , list* , search*
创建 create* , upload* , archive*
修改 update* , modify*
删除 delete* , clear* , remove*
强制规则
-
✅ 服务间通过 API 接口通信，禁止直接访问其他服务的数据库
-
✅ 依赖关系在 build.gradle.kts 中明确声明
-
❌ 禁止循环依赖
-
❌ 禁止手写 SQL，使用 JOOQ
Checklist
开发后端功能前确认：
-
功能归属到合理的现有服务
-
Resource 命名符合前缀规范
-
使用构造器注入依赖
-
返回值使用 Result<T> 包装
-
添加 Swagger 注解生成文档