Back to Details

backend-microservice-development

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

后端微服务开发

后端微服务开发

Quick Reference

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*(外部)
核心服务：process(流水线) | project(项目) | repository(代码库) | auth(权限)
四层架构：api-{service}(接口) → biz-{service}(业务+DAO) → boot-{service}(启动) → model-{service}(数据模型)
包命名：com.tencent.devops.<module>
Resource 前缀：User*(Web) | Service*(内部) | Build*(Agent) | Open*(外部)

最简示例

最简示例

kotlin
// 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
kotlin
// 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

When to Use

  • 创建新微服务或添加新 Resource
  • 编写 Kotlin/Java 后端代码
  • 设计服务间调用架构
  • 需要了解项目分层规范
  • 创建新微服务或添加新 Resource
  • 编写 Kotlin/Java 后端代码
  • 设计服务间调用架构
  • 需要了解项目分层规范

When NOT to Use

When NOT to Use

  • 前端 Vue 开发 → 使用 
    04-frontend-vue-development
  • Agent Go 开发 → 使用 
    05-go-agent-development
  • 数据库 DDL 编写 → 使用 
    database-design
  • 前端 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 生成的数据库访问对象
core/{service}/
├── api-{service}/      # API接口定义层 - 对外暴露服务契约
├── biz-{service}/      # 业务逻辑层 - 包含 Service、DAO
├── boot-{service}/     # Spring Boot启动层 - 独立部署单元
└── model-{service}/    # 数据模型层 - JOOQ 生成的数据库访问对象

16 个核心微服务

16 个核心微服务

服务职责
project项目管理（所有模块基础依赖）
process流水线编排与调度（核心服务）
repository代码库管理
artifactory制品库（对接 COS/S3）
store研发商店（插件、模板）
environment构建机/环境管理
dispatch构建调度分发
auth权限认证（RBAC）
ticket凭证管理
log构建日志
quality质量红线
notify通知服务
openapi对外 API
metrics度量服务
websocketWebSocket 服务
misc杂项服务
服务职责
project项目管理（所有模块基础依赖）
process流水线编排与调度（核心服务）
repository代码库管理
artifactory制品库（对接 COS/S3）
store研发商店（插件、模板）
environment构建机/环境管理
dispatch构建调度分发
auth权限认证（RBAC）
ticket凭证管理
log构建日志
quality质量红线
notify通知服务
openapi对外 API
metrics度量服务
websocketWebSocket 服务
misc杂项服务

Resource 命名规范

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
前缀用途路径前缀示例
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 定义

API 定义

kotlin
@RestResource              // REST 资源实现类
@Path("/user/artifactories")
@GET / @POST / @PUT / @DELETE
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
kotlin
@RestResource              // REST 资源实现类
@Path("/user/artifactories")
@GET / @POST / @PUT / @DELETE
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)

Swagger 文档

Swagger 文档

kotlin
@Tag(name = "USER_ARTIFACTORY", description = "版本仓库-仓库资源")
@Operation(summary = "根据元数据获取文件")
@Parameter(description = "用户ID", required = true)
kotlin
@Tag(name = "USER_ARTIFACTORY", description = "版本仓库-仓库资源")
@Operation(summary = "根据元数据获取文件")
@Parameter(description = "用户ID", required = true)

参数校验

参数校验

kotlin
@BkField(minLength = 1, maxLength = 128)
@BkField(patternStyle = BkStyleEnum.CODE_STYLE)
kotlin
@BkField(minLength = 1, maxLength = 128)
@BkField(patternStyle = BkStyleEnum.CODE_STYLE)

方法命名约定

方法命名约定

操作命名前缀
查询
get*
, 
query*
, 
list*
, 
search*
创建
create*
, 
upload*
, 
archive*
修改
update*
, 
modify*
删除
delete*
, 
clear*
, 
remove*
操作命名前缀
查询
get*
, 
query*
, 
list*
, 
search*
创建
create*
, 
upload*
, 
archive*
修改
update*
, 
modify*
删除
delete*
, 
clear*
, 
remove*

强制规则

强制规则

  • ✅ 服务间通过 API 接口通信，禁止直接访问其他服务的数据库
  • ✅ 依赖关系在 
    build.gradle.kts
    中明确声明
  • ❌ 禁止循环依赖
  • ❌ 禁止手写 SQL，使用 JOOQ
  • ✅ 服务间通过 API 接口通信，禁止直接访问其他服务的数据库
  • ✅ 依赖关系在 
    build.gradle.kts
    中明确声明
  • ❌ 禁止循环依赖
  • ❌ 禁止手写 SQL，使用 JOOQ

Checklist

Checklist

开发后端功能前确认：
  • 功能归属到合理的现有服务
  • Resource 命名符合前缀规范
  • 使用构造器注入依赖
  • 返回值使用 
    Result<T>
    包装
  • 添加 Swagger 注解生成文档
开发后端功能前确认：
  • 功能归属到合理的现有服务
  • Resource 命名符合前缀规范
  • 使用构造器注入依赖
  • 返回值使用 
    Result<T>
    包装
  • 添加 Swagger 注解生成文档