📚 课程目录第3章服务画像建模

3. 服务画像建模：如何构建服务画像数据模型，关键字段与元数据设计

服务画像建模是质量门禁工程的数据基石。没有标准化的画像模型，DORA Metrics 的采集口径、计算逻辑和对比基准就无法统一。本章将定义服务画像的核心数据模型，包括实体关系、关键字段和元数据规范，确保后续的度量与门禁策略建立在可复用的结构化数据之上。

3.1 服务画像实体关系模型

服务画像并非单表结构，而是由多个实体组成的星型或雪花型模型。核心实体包括：服务基本信息、部署单元、流水线元数据、团队归属和环境拓扑。下图展示了服务画像的顶层实体关系：

3.2 关键字段设计

服务画像数据模型包含五大核心表，每张表的关键字段设计如下：

3.2.1 服务基本信息表（service_profile）

字段名	类型	约束	说明
service_id	VARCHAR(64)	PK, NOT NULL	全局唯一服务标识，如 svc-order-001
service_name	VARCHAR(128)	NOT NULL	服务名称，如 "订单服务"
service_type	VARCHAR(32)	NOT NULL	服务类型：微服务 / 单体 / 函数 / 批处理
language	VARCHAR(32)	DEFAULT 'unknown'	主要编程语言，如 Java / Go / Python
repo_url	VARCHAR(512)	NOT NULL	源代码仓库地址
created_at	TIMESTAMP	NOT NULL	服务首次注册时间
updated_at	TIMESTAMP	ON UPDATE CURRENT_TIMESTAMP	最后更新时间

3.2.2 部署单元表（deployment_unit）

字段名	类型	约束	说明
unit_id	VARCHAR(64)	PK, NOT NULL	部署单元唯一标识
service_id	VARCHAR(64)	FK → service_profile	所属服务
unit_name	VARCHAR(128)	NOT NULL	单元名称，如 "order-api-v2"
container_image	VARCHAR(256)	NOT NULL	容器镜像地址（含标签）
replicas	INT	DEFAULT 1	期望副本数
health_check_path	VARCHAR(128)	DEFAULT '/health'	健康检查端点

3.2.3 流水线元数据表（pipeline_metadata）

字段名	类型	约束	说明
pipeline_id	VARCHAR(64)	PK, NOT NULL	流水线运行唯一 ID
service_id	VARCHAR(64)	FK → service_profile	关联服务
trigger_type	VARCHAR(16)	NOT NULL	触发方式：push / pr / schedule / manual
commit_sha	VARCHAR(40)	NOT NULL	触发提交的 SHA
branch	VARCHAR(128)	NOT NULL	分支名称
started_at	TIMESTAMP	NOT NULL	流水线开始时间
finished_at	TIMESTAMP	NULL	流水线结束时间（NULL 表示运行中）
status	VARCHAR(16)	NOT NULL	状态：success / failure / running / cancelled

3.2.4 团队归属表（team_ownership）

字段名	类型	约束	说明
team_id	VARCHAR(32)	PK, NOT NULL	团队唯一标识，如 "team-payment"
service_id	VARCHAR(64)	FK → service_profile	关联服务
owner_type	VARCHAR(16)	NOT NULL	归属类型：primary / secondary / contributor
slack_channel	VARCHAR(64)	NULL	团队通知频道
oncall_rotation	VARCHAR(256)	NULL	值班轮转 PagerDuty 链接

3.2.5 环境拓扑表（environment_topology）

字段名	类型	约束	说明
env_id	VARCHAR(32)	PK, NOT NULL	环境标识，如 "prod-cn-east"
service_id	VARCHAR(64)	FK → service_profile	关联服务
env_name	VARCHAR(32)	NOT NULL	环境名称：dev / staging / prod
cluster	VARCHAR(128)	NOT NULL	K8s 集群名称或 ID
namespace	VARCHAR(64)	NOT NULL	K8s 命名空间
ingress_domain	VARCHAR(256)	NULL	对外访问域名

设计要点：所有表均采用 VARCHAR 主键而非自增 ID，确保跨环境、跨集群的数据合并时不会产生冲突。时间字段统一使用 UTC 时间戳，避免时区转换带来的度量偏差。

3.3 元数据设计规范

元数据是服务画像的“数据之数据”，用于描述字段的语义、来源、更新频率和校验规则。良好的元数据设计能大幅降低数据治理成本。

3.3.1 元数据分类

技术元数据：字段类型、长度、索引、默认值、是否可为空。
业务元数据：字段的业务含义、枚举值说明、计算口径、所属域（如 DORA 域 / 成本域）。
操作元数据：数据来源系统（如 Jenkins / ArgoCD / GitHub）、采集时间戳、数据版本号、变更记录。

3.3.2 元数据存储结构

推荐使用独立的元数据表或 JSON Schema 文件来管理。以下是一个基于 JSON Schema 的元数据定义示例：

{
  "field": "deploy_frequency",
  "type": "float",
  "business_domain": "DORA",
  "description": "每日部署次数，计算口径：过去30天成功部署次数 / 30",
  "source_system": "pipeline_metadata",
  "refresh_frequency": "daily",
  "validation_rules": [
    {"rule": "value >= 0", "error_msg": "部署频率不能为负数"},
    {"rule": "value <= 100", "error_msg": "单日部署频率超过阈值，请确认数据"}
  ],
  "tags": ["DORA", "velocity", "deployment"]
}

3.4 服务画像数据模型总览

将上述实体和字段整合为完整的服务画像数据模型，便于后续开发人员直接参考建表：

3.5 字段命名与类型规范

为保证跨团队、跨工具链的一致性，服务画像的字段命名需遵循以下规范：

全小写 + 下划线：如 deploy_frequency、change_failure_rate，禁止使用驼峰或大小写混用。
前缀表示所属域：DORA 相关字段以 dora_ 开头（如 dora_deploy_freq），基础设施字段以 infra_ 开头。
时间字段统一后缀：开始时间用 _at（如 started_at），持续时长用 _duration_seconds。
枚举字段使用 VARCHAR 存储：避免使用 INT 枚举，便于直接可读和跨系统迁移。

避坑提醒：不要在服务画像表中直接存储 DORA 计算指标（如部署频率的数值）。画像表只存储原始事件和元数据，指标计算应通过物化视图或实时计算层完成，避免数据冗余和更新异常。

3.6 数据模型版本管理

服务画像模型会随着业务演进不断调整。建议采用以下版本管理策略：

模型版本号：在元数据表中记录 model_version 字段，格式为 v{major}.{minor}（如 v2.1）。
向后兼容：新增字段必须允许为 NULL 或设置默认值，禁止删除或重命名已有字段。
变更审批流程：所有模型变更需通过 Pull Request 修改 JSON Schema 文件，并触发自动化兼容性检查。
数据迁移脚本：每个版本对应一个可回滚的迁移脚本，存储在 migrations/ 目录下。

-- 示例：v2.0 到 v2.1 的迁移脚本
ALTER TABLE service_profile
  ADD COLUMN dora_team_id VARCHAR(32) NULL COMMENT '关联的 DORA 度量团队标识',
  ADD INDEX idx_dora_team (dora_team_id);

通过上述建模方法，服务画像数据模型将为后续的 DORA Metrics 采集、质量门禁策略配置和跨服务对比分析提供稳定、可扩展的数据底座。