📚 课程目录第4章数据采集与接入层工程

4. 数据采集与接入层工程

数据采集与接入层是药物研发数据平台的第一道工程关口。它面对的不是单一数据库，而是实验室仪器、EDC、CTMS、LIMS 以及外部公共数据库等异构数据源。这些数据源在协议、数据格式、触发方式、时间语义和更新频率上差异极大，因此接入层工程的核心任务不是“把数据搬进来”，而是建立一套可配置、可观测、可追溯的协议适配与调度体系，使实时流与批量文件在同一套元数据治理下汇入平台。

一、先按“触发方式 + 数据形态”给数据源分类

接入方案的第一步是分类，而不是直接写连接器。建议用两个维度判断：触发方式是推送还是拉取，数据形态是流式记录、结构化事务还是文件。实验室仪器（如 HPLC、酶标仪、流式细胞仪）通常以文件或本地数据库形式输出，部分支持 HL7、ASTM 或厂商私有协议；EDC 系统多提供 REST API 或增量导出，按受试者访视产生结构化记录；CTMS 以项目、中心、里程碑等管理数据为主，更新频率低但字段稳定；LIMS 承载样本、检测、结果与质控数据，常通过数据库视图或消息队列暴露；外部数据库（如 ClinicalTrials.gov、PubChem、UniProt）则以批量下载或 API 分页拉取为主。

分类之后，接入层应形成三条并行通道：实时通道用于仪器信号与关键状态事件，批量通道用于 EDC/CTMS/LIMS 的定时抽取，外部通道用于公共库的周期同步。三条通道共享同一份数据源注册表、字段映射规则和血缘记录，避免形成三套孤立的管道。

二、协议适配的关键实现

协议适配层是接入工程中最需要“写清楚”的部分。以实验室仪器为例，若仪器通过文件输出，常见做法是监听共享目录，用文件到达事件触发解析。解析器需要处理厂商私有格式，例如某酶标仪导出的 CSV 中，前 8 行是仪器元数据，第 9 行才是表头，且孔位坐标以 A1、B2 形式表示。适配器应把孔位转换为行列号，把 OD 值转换为标准单位，并记录原始文件哈希，防止重复解析。

对于 EDC 和 CTMS，推荐使用增量拉取而非全量覆盖。以 EDC 为例，接口通常支持按 updated_at 或 visit_date 过滤。调度器每次记录上次成功拉取的最大时间戳，下一次从该时间戳开始请求。若接口不支持时间过滤，则退化为按受试者 ID 分页拉取，并在本地维护版本号。LIMS 若提供数据库只读视图，可用 JDBC 批量读取，但必须限制查询窗口，避免长事务影响生产库。

# 示例：EDC 增量拉取配置（教学示例，非真实系统参数）
source: edc_prod
endpoint: https://edc.example.org/api/v2/subjects
auth: oauth2_client_credentials
incremental_field: updated_at
page_size: 200
schedule: "0 */2 * * *"   # 每 2 小时
mapping:
  subject_id: SUBJID
  visit: VISIT
  form_date: FOMDTC
  value: OVAL
  unit: ORESU

外部数据库接入要特别注意速率限制与数据版本。以 ClinicalTrials.gov 为例，API 通常按页返回，每页最多 1000 条，且需要处理 nextPageToken。适配器应实现指数退避重试，遇到 429 状态码时暂停并记录，而不是无限重试。PubChem 等化学数据库则更适合按 CID 批量下载 SDF 文件，再解析为结构记录。

三、实时与批量的协同

实时通道和批量通道不是互斥的。仪器产生的原始信号可以实时进入消息队列，用于状态监控和异常告警；而最终结果文件仍走批量解析，进入标准层。这样做的原因是：实时流适合低延迟事件，但结果数据的完整性、版本和审计要求更高，批量通道更容易实现幂等和重放。

接入层还应统一时间语义。建议所有记录携带三个时间：源系统事件时间、接入层接收时间、写入标准层时间。当出现数据延迟或乱序时，以源系统事件时间作为业务判断依据，接收时间用于监控管道健康度。对于跨时区的外部数据库，统一转换为 UTC 存储，并在元数据中保留原始时区。

接入层的最小可观测指标建议包括：每个数据源的最近成功时间、最近失败原因、待处理积压量、平均端到端延迟、重复记录拦截数。这些指标比“是否连通”更能反映真实接入质量。

四、一个可执行的接入检查清单

在把任何一个新数据源接入平台前，建议按以下清单逐项确认，避免后期返工：

数据源类型与触发方式：推送还是拉取，实时还是批量，是否支持增量。
协议与认证：REST、JDBC、SFTP、MQTT 或私有协议，认证方式与凭据轮换策略。
主键与版本：源系统唯一标识是什么，是否可能重复，如何判断更新与删除。
字段映射：源字段到标准模型的对应关系，单位、编码、时间格式的转换规则。
失败处理：重试次数、退避策略、死信队列、人工补录入口。
审计与血缘：批次号、文件哈希、操作者、源系统时间戳是否完整记录。
验收标准：抽样比对源系统与平台记录数、关键字段一致率、延迟是否在约定范围内。

完成上述配置后，接入层才算真正具备工程可用性。它不追求把所有数据源变成同一种协议，而是通过适配层把差异收敛到可管理的元数据中，使实时与批量、内部与外部数据能够在同一套治理框架下持续汇入平台。