日志采集接口设计原则

接口设计这件事，说白了就是定规矩。规矩定得好，后面几十年都省事；定得不好，天天填坑。我经历过几次大翻车，后来慢慢总结出三个核心原则：标准化、可扩展、安全性。这三个词不是挂在墙上的口号，是真金白银踩出来的。

2.1 标准化——让不同系统说同一种语言

为什么标准化排第一？你想想看，外发审计日志要对接几十甚至上百个业务系统。每个系统各自设计一套接口，那对接团队就等着加班加到怀疑人生吧。

我遇到过一家客户，他们的内部系统用 XML、JSON、Protobuf 三种格式混着发。光解析层就写了四套代码，每次加字段还要同步改。最后我建议他们统一成 JSON + 固定字段映射，维护成本降了60%。

标准化包含几个关键维度：

• 数据格式统一：建议使用 JSON 或 Protobuf，拒绝自造格式。我个人偏向 JSON，调试方便，生态成熟。
• 字段命名规范：统一小驼峰或下划线，别混用。比如 eventTime 就全用 eventTime，不要一半 event_time。
• 必选字段约束：日志 ID、时间戳、事件类型、来源系统、操作人——这五个字段必须出现。缺一个，整个日志就没法串联。
• 枚举值统一：事件类型、状态码、错误码全部定义在公共枚举表里。我曾经见过同一业务场景用 “SUCCESS”、“success”、“1” 三种表示，后面做统计分析直接崩溃。

标准化字段清单示例

字段名	类型	必填	说明
logId	string	是	全局唯一日志ID
eventTime	long	是	事件发生时间戳（毫秒）
eventType	string	是	预定义事件类型枚举
sourceSystem	string	是	来源系统标识
operator	string	是	操作人账号
payload	object	否	扩展数据体，结构可动态变化

2.2 可扩展——给未来留下改的空间

日志采集场景变化太快。今天只收操作日志，明天可能增加网络日志、数据库变更日志。如果接口设计死了，后面只能推倒重来。

我的经验是：把不变的和变的分开。固定字段管通用，扩展字段管个性。

// 坏例子——扩展只能加新字段
{
  "logId": "xxx",
  "eventTime": 123,
  "eventType": "OPERATION",
  "operationName": "退单",         // 只兼容操作日志
}

// 好例子——用 payload 承载扩展数据
{
  "logId": "xxx",
  "eventTime": 123,
  "eventType": "OPERATION",
  "payload": {                     // 完全自定义
    "operationName": "退单",
    "orderId": "ORD2024...",
    "amount": 100.00
  }
}

可扩展性原则还体现在：

• 字段预留：每个对象都留一个 extensions 或 tags 字段，Map 类型，key-value 随意扩展。
• 版本宽容：接口支持向后兼容。新版本不能删除旧字段，只能增加可选字段。
• 插件式采集：采集端设计成 SPI 或插件架构，每个业务模块可以独立注册自己的日志解析器。
• 动态 Schema：对于复杂场景，可以引入 Schema Registry，让采集端动态拉取日志结构定义。

2.3 安全性——别让日志成为攻击入口

外发日志采集接口是暴露在公网或跨网络边界的，很容成为攻击目标。我记得有个项目，日志采集接口没有做身份认证，结果内网的一个测试脚本误把全量业务数据发到生产采集端，导致审计系统崩溃了两小时。

安全性我归纳为四个层次：

1. 身份认证：每个请求必须携带有效的 AccessKey + Signature 或 JWT 。不能裸奔。
2. 传输加密：强制使用 HTTPS，TLS 1.2+。数据在传输过程中必须加密，不能让中间人抓到明文。
3. 权限控制：每条日志只能写入，不能读取。采集接口只开放 POST，不开放 GET/ DELETE。避免信息泄露。
4. 数据脱敏：对于敏感字段（身份证、手机号、密码等），在日志源头就完成脱敏再入库。采集端只接收脱敏后的数据。

安全防护级别对比

层次	具体措施	推荐级别
传输层	HTTPS + 双向证书校验	强制
认证层	HMAC-SHA256 签名或 OAuth2	强制
鉴权层	最小权限原则，只写不读	强制
数据层	自动脱敏 + 审计日志防篡改哈希链	建议

2.4 三条原则的关系：一个不等式

标准化和可扩展有时候是矛盾的。标准化要求约定死，可扩展要求留活口。怎么平衡？我的做法是：固定骨架，放开血肉。骨架用标准化约束，血肉用扩展机制支持。

安全性则像一条底裤，必须保证每个环节都穿上。哪怕标准化做得再好，接口裸奔也没用。

你看，三个原则环环相扣。标准化定义接口的通用结构，可扩展支撑业务变化，安全性保证全过程可信。任何一个环节出问题，整个审计日志链路就塌了。