JRY's digital garden

数据服务与API层

9 min read

数据服务与API层

数据服务与API层是工厂数据平台总体架构的”门面”——它将工厂数据仓库建模中精心组织的数据和实时数据流水线产出的实时指标，以标准化的服务接口对外暴露，实现数据生产与数据消费的彻底解耦。没有这一层，每个数据消费者（报表、看板、第三方系统）都需要直接访问底层数据库，导致紧耦合、安全风险和维护噩梦。

数据服务化的意义

解耦数据生产与消费

传统做法中，看板开发者需要知道底层数据库的表结构、字段含义、计算逻辑。当工厂数据仓库建模中的模型调整时，所有下游应用都要跟着改。引入API层后：

  • 看板只调用”获取OEE趋势”的API，不关心底层是Doris还是Hive
  • 数仓模型调整只影响API实现，不影响API接口
  • 新增数据消费者只需调用现有API，无需重复开发

统一数据口径

不同部门可能对同一指标有不同理解。通过API层统一提供指标计算结果：

  • OEE-设备综合效率的计算逻辑由API统一封装，所有消费者得到一致的OEE值
  • 良率-Yield的口径（是否包含返工品）在API层明确并统一执行
  • 避免各部门”各自计算、数字打架”的问题

指标API设计

API分层

按照数据时效性分为两类API：

实时指标API（数据来自实时数据流水线）：

  • GET /api/v1/oee/realtime?line_id=L01 — 获取产线实时OEE
  • GET /api/v1/production/realtime/status — 获取全厂产线状态概览
  • 数据源：Doris实时表或Redis缓存
  • 响应要求：< 500ms，支持WebSocket推送

历史指标API（数据来自数仓ADS层）：

  • GET /api/v1/oee/history?line_id=L01&start=2026-05-01&end=2026-05-18 — 获取历史OEE趋势
  • GET /api/v1/quality/daily?product_id=P001&granularity=day — 获取质量日报数据
  • 数据源：Doris或ClickHouse
  • 响应要求：< 2s

API设计规范

# RESTful风格
GET    /api/v1/{domain}/{metric}          # 查询指标
GET    /api/v1/{domain}/{metric}/history   # 历史查询
POST   /api/v1/{domain}/{metric}/compare   # 对比分析

# 示例：获取设备OEE排行榜
GET /api/v1/equipment/oee/ranking?factory=SH&period=2026-W20&top=10

# 示例：获取产线良率趋势
GET /api/v1/production/yield/trend?line_id=L01&start=2026-04-01&end=2026-05-18&granularity=day

指标注册中心

为每个指标建立注册信息：

  • 指标名称、英文名、业务口径定义
  • 计算公式、数据来源、更新频率
  • 负责人、审批状态
  • 与工厂主数据管理中的维度关联

报表服务

报表类型

报表类型频率主要内容分发方式
生产日报每日产量、OEE、质量、异常事件邮件/企业微信
质量周报每周合格率趋势、Top缺陷、CPK分析邮件/系统
设备月报每月MTBF/MTTR、故障分析、维保计划完成率邮件/系统
成本月报每月能耗、人工、废品成本分析邮件/系统

报表生成流程

  1. 模板定义：使用JasperReports或自研模板引擎定义报表模板
  2. 数据填充：定时任务（如每日06:00）调用指标API获取数据并填充模板
  3. 格式输出：生成PDF/Excel/HTML格式
  4. 自动分发：通过邮件、企业微信或ERP-企业资源计划系统分发
  5. 异常告警：关键指标超出阈值时在报表中高亮标注

自助式报表

为业务人员提供自助式报表工具：

  • 拖拽式报表设计器，无需编写SQL
  • 预置常用指标和维度（来自指标注册中心）
  • 支持条件格式、钻取分析
  • 报表保存、分享和订阅

看板技术选型

方案对比

方案优势劣势适用场景
Grafana开源免费、数据源丰富、部署简单定制性有限、工业场景支持弱设备监控、实时数据
Superset开源、可视化丰富、支持SQL实时性一般、定制开发量大数据分析、报表
自研(React/ECharts)完全定制、用户体验好开发成本高、维护成本高管理驾驶舱、车间看板
商业BI平台功能全面、技术支持费用高、灵活性受限企业级BI

推荐组合方案

  • 车间操作看板：Grafana，快速部署，满足实时监控需求
  • 管理驾驶舱：自研（React + ECharts），实现定制化的工业风格大屏
  • 数据分析平台：Superset，供工程师自助分析

看板设计原则

  1. 信息层次清晰：总览 → 产线 → 设备 → 参数，层层钻取
  2. 异常优先展示：告警信息、异常指标置顶
  3. 颜色语义统一：绿色=正常、黄色=预警、红色=异常
  4. 刷新策略合理：操作看板10秒刷新，管理看板5分钟刷新
  5. 移动端适配：车间管理者需要通过手机查看关键指标

数据服务治理

权限控制

数据服务必须实现细粒度的权限控制：

  • 功能权限：哪些API可以被哪些角色调用
  • 数据权限：同一API，不同角色看到不同范围的数据（如车间主任只看本车间数据）
  • 维度权限：某些敏感数据（如成本数据）需要额外授权

权限模型：RBAC（基于角色的访问控制），角色定义参考ISA-95参考架构中的组织层级。

限流与容错

  • 限流策略：每个API设置QPS上限，防止慢查询拖垮整个服务
  • 熔断机制：当底层数据源响应超时时，返回缓存数据或降级响应
  • 超时设置：实时API 3s超时，历史API 10s超时
  • 重试策略：对于临时性故障，支持自动重试（最多2次）

版本管理

API必须进行版本管理，确保向后兼容：

  • URL中包含版本号：/api/v1/、/api/v2/
  • 新版本上线时，老版本至少保留6个月
  • 版本变更记录在API文档中，通知所有消费者

监控与日志

  • 调用监控：每个API的调用量、响应时间、错误率
  • 访问日志：谁在什么时间调用了什么API，查询了什么参数
  • 审计追踪：敏感数据访问记录，满足工业数据安全合规要求

实施路径

  1. 第一阶段：梳理核心指标（OEE、良率、产量），实现指标API，搭建Grafana看板
  2. 第二阶段：完善报表服务，实现自动生成与分发，建设自助分析平台
  3. 第三阶段：建设管理驾驶舱大屏，实现全厂数据可视化
  4. 第四阶段：完善服务治理（权限、限流、监控），形成标准化数据服务体系

数据服务与API层的建设，让工厂数据平台总体架构中的数据价值得以真正释放——从”数据在仓库里”到”数据在决策中”，这一层是关键的转化桥梁。

Graph View

Backlinks