| name | 38-quality-module-architecture |
| description | Quality 质量红线模块架构指南，涵盖质量规则管理、指标配置、准入准出控制点、红线拦截与放行机制。当用户需要开发质量管控功能、配置质量红线、实现质量检查拦截时使用。 |
Quality 质量红线模块架构指南
概述
Quality（质量红线）模块是 BK-CI 的质量管控服务，负责在流水线执行过程中进行质量检查和拦截，确保只有符合质量标准的构建才能继续执行或发布。
模块职责：
- 质量规则管理（创建、编辑、启用/禁用）
- 质量指标管理（内置指标、自定义指标）
- 控制点管理（准入/准出检查点）
- 质量红线拦截与放行
- 质量数据统计与报表
一、模块结构
src/backend/ci/core/quality/
├── api-quality/ # API 接口定义
│ └── src/main/kotlin/com/tencent/devops/quality/
│ ├── api/ # Resource 接口
│ │ ├── UserGroupResource.kt
│ │ ├── v2/ # V2 版本 API
│ │ │ ├── UserQualityRuleResource.kt
│ │ │ ├── ServiceQualityRuleResource.kt
│ │ │ ├── UserQualityIndicatorResource.kt
│ │ │ └── ...
│ │ └── v3/ # V3 版本 API
│ ├── constant/ # 常量定义
│ │ ├── QualityMessageCode.kt
│ │ ├── I18nConstants.kt
│ │ └── MQ.kt
│ └── pojo/ # 数据传输对象
│ ├── QualityRule*.kt
│ ├── Group*.kt
│ └── RuleInterceptHistory.kt
├── biz-quality/ # 业务逻辑层
└── boot-quality/ # 启动模块
二、核心概念
2.1 质量红线模型
┌─────────────────────────────────────────────────────────────────────────┐
│ 质量红线核心模型 │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ 质量规则 (Quality Rule) │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │
│ │ │ 规则名称 │ │ 控制点 │ │ 指标阈值列表 │ │ │
│ │ │ (name) │ │ (control │ │ (indicator_range) │ │ │
│ │ │ │ │ point) │ │ │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────┐ │ │
│ │ │ 生效范围 │ │ │
│ │ │ pipeline_template_range | indicator_range │ │ │
│ │ └─────────────────────────────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ 控制点 (Control Point) │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │
│ │ │ 原子类型 │ │ 研发阶段 │ │ 红线位置 │ │ │
│ │ │ (element │ │ (stage) │ │ (BEFORE/AFTER) │ │ │
│ │ │ type) │ │ │ │ │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ 质量指标 (Indicator) │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │
│ │ │ 指标名称 │ │ 数据类型 │ │ 阈值操作 │ │ │
│ │ │ (name) │ │ (data_type) │ │ (>=, <=, =, !=) │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
2.2 核心实体关系
| 实体 | 说明 | 关系 |
|---|---|---|
| Quality Rule | 质量规则 | 包含多个指标阈值 |
| Control Point | 控制点 | 关联到流水线原子 |
| Indicator | 质量指标 | 定义检查项和阈值 |
| Metadata | 元数据 | 指标的数据来源 |
| History | 拦截历史 | 记录每次检查结果 |
2.3 红线位置
enum class ControlPointPosition {
BEFORE, // 准入检查（原子执行前）
AFTER // 准出检查（原子执行后）
}
三、数据库设计
3.1 核心表结构
| 表名 | 说明 |
|---|---|
T_QUALITY_RULE |
质量规则表 |
T_QUALITY_CONTROL_POINT |
控制点表 |
T_QUALITY_INDICATOR |
质量指标表 |
T_QUALITY_METADATA |
指标元数据表 |
T_QUALITY_HIS_DETAIL_METADATA |
历史元数据详情 |
T_HISTORY |
拦截历史记录 |
T_GROUP |
通知组（红线触发通知） |
T_COUNT_INTERCEPT |
拦截统计（按项目/日期） |
T_COUNT_PIPELINE |
流水线拦截统计 |
T_COUNT_RULE |
规则拦截统计 |
T_CONTROL_POINT |
控制点定义 |
T_CONTROL_POINT_METADATA |
控制点元数据 |
T_CONTROL_POINT_TASK |
控制点任务 |
3.2 关键字段说明
T_QUALITY_RULE：
- ID: 规则主键
- NAME: 规则名称
- PROJECT_ID: 项目ID（english_name）
- CONTROL_POINT: 控制点原子类型
- CONTROL_POINT_POSITION: 红线位置（BEFORE/AFTER）
- INDICATOR_RANGE: 指标阈值范围（JSON）
- PIPELINE_TEMPLATE_RANGE: 生效流水线/模板范围
- ENABLE: 是否启用
- GATEWAY_ID: 红线匹配ID
T_QUALITY_INDICATOR：
- ID: 指标主键
- ELEMENT_TYPE: 关联的原子类型
- ELEMENT_NAME: 原子名称
- ELEMENT_DETAIL: 原子详情
- EN_NAME: 英文名称
- CN_NAME: 中文名称
- METADATA_IDS: 关联的元数据ID
- DEFAULT_OPERATION: 默认操作符
- OPERATION_AVAILABLE: 可用操作符
- THRESHOLD: 阈值
- THRESHOLD_TYPE: 阈值类型
四、API 接口设计
4.1 用户级接口
@Path("/user/rules")
interface UserQualityRuleResource {
@POST
@Path("/projects/{projectId}/create")
fun create(
@PathParam("projectId") projectId: String,
@HeaderParam(AUTH_HEADER_USER_ID) userId: String,
rule: RuleCreate
): Result<String>
@GET
@Path("/projects/{projectId}/list")
fun list(
@PathParam("projectId") projectId: String,
@QueryParam("page") page: Int?,
@QueryParam("pageSize") pageSize: Int?
): Result<Page<QualityRule>>
@PUT
@Path("/projects/{projectId}/{ruleHashId}/update")
fun update(
@PathParam("projectId") projectId: String,
@PathParam("ruleHashId") ruleHashId: String,
rule: RuleUpdate
): Result<Boolean>
@DELETE
@Path("/projects/{projectId}/{ruleHashId}/delete")
fun delete(
@PathParam("projectId") projectId: String,
@PathParam("ruleHashId") ruleHashId: String
): Result<Boolean>
}
4.2 服务间接口
@Path("/service/rules")
interface ServiceQualityRuleResource {
@POST
@Path("/projects/{projectId}/pipelines/{pipelineId}/builds/{buildId}/check")
fun check(
@PathParam("projectId") projectId: String,
@PathParam("pipelineId") pipelineId: String,
@PathParam("buildId") buildId: String,
request: QualityCheckRequest
): Result<QualityCheckResult>
@GET
@Path("/projects/{projectId}/matchRuleList")
fun matchRuleList(
@PathParam("projectId") projectId: String,
@QueryParam("pipelineId") pipelineId: String
): Result<List<QualityRule>>
}
4.3 构建过程接口
@Path("/build/quality")
interface BuildQualityMetadataResource {
@POST
@Path("/projects/{projectId}/pipelines/{pipelineId}/builds/{buildId}/metadata/save")
fun saveMetadata(
@PathParam("projectId") projectId: String,
@PathParam("pipelineId") pipelineId: String,
@PathParam("buildId") buildId: String,
metadata: List<QualityMetadata>
): Result<Boolean>
}
五、质量检查流程
5.1 红线检查时序
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ Process │ │ Quality │ │ 指标 │ │ 历史 │
│ Engine │ │ Service │ │ Service │ │ Service │
└────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘
│ │ │ │
│ 1.检查红线 │ │ │
│──────────────>│ │ │
│ │ │ │
│ │ 2.获取匹配规则│ │
│ │──────────────>│ │
│ │ │ │
│ │ 3.获取指标数据│ │
│ │<──────────────│ │
│ │ │ │
│ │ 4.比对阈值 │ │
│ │───────┐ │ │
│ │ │ │ │
│ │<──────┘ │ │
│ │ │ │
│ │ 5.记录历史 │ │
│ │──────────────────────────────>│
│ │ │ │
│ 6.返回结果 │ │ │
│<──────────────│ │ │
│ │ │ │
│ 7.拦截/放行 │ │ │
│───────┐ │ │ │
│ │ │ │ │
│<──────┘ │ │ │
5.2 检查结果处理
enum class QualityCheckResult {
PASS, // 通过
FAIL, // 失败（拦截）
WAIT, // 等待审核
INTERCEPT // 已拦截
}
六、与其他模块的关系
6.1 依赖关系
Quality 模块
│
├──> Process（流水线）
│ - 在流水线执行时触发质量检查
│ - 根据检查结果决定是否继续执行
│
├──> Store（研发商店）
│ - 获取插件的控制点定义
│ - 获取插件的质量指标元数据
│
├──> Project（项目）
│ - 获取项目信息
│ - 项目级别的质量规则管理
│
└──> Notify（通知）
- 红线触发时发送通知
- 通知审核人员
6.2 事件机制
// 质量检查事件
data class QualityCheckEvent(
val projectId: String,
val pipelineId: String,
val buildId: String,
val position: ControlPointPosition,
val elementType: String
)
// MQ 队列定义
object QualityMQ {
const val EXCHANGE_QUALITY_CHECK = "e.engine.quality.check"
const val QUEUE_QUALITY_CHECK = "q.engine.quality.check"
const val ROUTE_QUALITY_CHECK = "r.engine.quality.check"
}
七、开发规范
7.1 新增质量指标
- 在
T_QUALITY_INDICATOR表中注册指标 - 在对应插件中上报元数据
- 配置指标与控制点的关联
// 插件上报质量数据示例
val metadata = QualityMetadata(
elementType = "CodeCC",
data = mapOf(
"defectCount" to "10",
"coverageRate" to "85.5"
)
)
client.get(BuildQualityMetadataResource::class).saveMetadata(
projectId = projectId,
pipelineId = pipelineId,
buildId = buildId,
metadata = listOf(metadata)
)
7.2 新增控制点
- 在
T_QUALITY_CONTROL_POINT表中注册 - 配置支持的红线位置（BEFORE/AFTER）
- 关联可用的质量指标
7.3 自定义规则
// 创建质量规则
val rule = RuleCreate(
name = "代码扫描质量门禁",
desc = "代码扫描缺陷数不能超过10个",
controlPoint = "CodeCC",
controlPointPosition = "AFTER",
indicators = listOf(
RuleIndicator(
indicatorId = "defectCount",
operation = "<=",
threshold = "10"
)
),
range = listOf("*"), // 所有流水线
notifyGroupList = listOf(groupId)
)
八、常见问题
Q: 质量规则如何与流水线关联？
A: 通过 PIPELINE_TEMPLATE_RANGE 字段配置生效范围，支持：
- 指定流水线ID列表
- 指定流水线模板
*表示项目下所有流水线
Q: 红线拦截后如何处理？ A: 有三种处理方式：
- 自动拦截：构建失败
- 人工审核：等待审核人员决定
- 告警模式：仅发送通知，不拦截
Q: 如何查看拦截历史？
A: 通过 UserQualityInterceptResource 接口查询，或在前端"质量红线"页面查看。
版本: 1.0.0 | 更新日期: 2025-12-11