Utility Library Evolution
ODTS-40: 共享库演变（eds-utility, 2017-2026）
目标读者：需要理解 CICC OTC 系统中”无处不在却无人专门负责”的共享层的 BA/PM
数据来源：git 历史（4,444 commits, 82 authors, 2017-03-03 → 2026-06-29）
概述
eds-utility 是 CICC OTC 衍生品系统的共享类库，被 eds-web-app、hedging-as、sac-report、eds-price-server 等几乎所有 EDS 系统引用。它不是独立的进程，而是一个 JAR 包。
它的 4,444 个 commit 和 82 位贡献者说明：这不是一个”静态工具集合”，而是一个活跃演变的共享层，承载着跨系统共用的业务逻辑。
各年活跃度
2017: 236 commits ← 启动
2018: 261 ← 框架工具积累
2019: 162 ← 平稳
2020: 1,536 ← 峰值！v6.6 版本+大量新功能
2021: 940 ← 持续
2022: 450 ← 降速
2023: 224 ← 维护
2024: 188 ← 维护
2025: 65 ← 低活跃
2026: 43 ← 低活跃（仍在维护中）2020 年的 1,536 个 commit 是峰值，与 eds-web-app 和 hedging-as 的 v6.6 大版本对齐。
包结构演变
src/
├── com/framework/ ← 框架层（Yuping Ai 主导）
│ ├── database/ → ORM + 表结构定义
│ ├── util/ → 通用工具
│ ├── crypt/ → 加密/解密
│ ├── rpc/ → RPC 通信
│ ├── protobuf/ → ProtoBuf 序列化
│ └── h2db/ → H2 内存数据库
│
├── com/cicc/ ← 业务层
│ ├── quotation/ → 行情工具
│ ├── activeMQ/ → 消息队列工具
│ │ ├── RiskRule/ → 风控规则
│ │ ├── TransPara/ → 交易参数
│ │ └── AccountData/ → 账户数据
│ ├── dataCenter/ → 数据中心
│ │ └── pbMargin/ → ProtoBuf 保证金
│ ├── securities/ → 证券相关
│ │ ├── quotation/ → 证券行情
│ │ ├── hkstockexch/ → 港股通
│ │ └── util/ → 证券工具
│ └── vr/ → VR 模块
│
├── com/edsconst/ ← EDS 常量定义
├── com/domian/ ← 领域模型（mailInfo等）
└── com/framework/database/resource/ ← 数据库资源核心内容分类
1. 数据库层（database/）
eds-utility 定义了各表对应的 Java 类：
// 示例：表结构映射
public class MarginSnapshotTable {
public static final String TABLE_NAME = "margin_snapshot";
public static final String SNAPSHOT_ID = "snapshot_id";
public static final String MARGIN_TYPE = "margin_type";
public static final String MARGIN_AMOUNT = "margin_amount";
// ...
}这些表定义被所有 EDS 系统共享，保证数据库列名在不同系统间一致。
2. ProtoBuf 通信
Protobuf 的序列化/反序列化逻辑放在 eds-utility 中，确保 eds-web-app 和 hedging-as 之间的 RPC 通信兼容。
3. ActiveMQ 消息
定义了 ActiveMQ 消息队列的 topic/queue 名称和消息格式，是所有系统间异步通信的基础。
4. 行情工具（quotation/）
被 eds-web-app 和 hedging-as 共同引用的行情数据结构和计算工具——说明行情的处理逻辑在多个系统中重复使用。
5. 常量定义（edsconst/）
public interface EdsConst {
String PRODUCT_TYPE_SWAP = "SWAP";
String PRODUCT_TYPE_OPTION = "OPTION";
String PRODUCT_TYPE_STRUCTURED = "STRUCTURED";
// ...
}整个系统的业务常量和枚举类型都集中定义在这里。
版本线
v_1.6 → v_2.0_lib_1 → v_20201108 → v7.0.2 → v7.0.16eds-utility 的版本从 v1/v2 到 v7.0.x，后来与 eds-web-app 的版本号对齐。
峰值（2020年）
2020 年的 1,536 个 commit 是 eds-utility 的峰值，同期 eds-web-app 和 hedging-as 也在 v6.6 大版本的高峰期。这说明：
- 跨系统代码被大量迁移到共享库——减少重复代码
- v6.6 并非单一发布——它是一次系统的整体重构
- 共享库的扩展不全是工具类——大量业务逻辑存在于共享库中
业务代价：共享库出问题时的真实成本
JAR 版本不兼容——“你升级了，我没升级”
eds-utility 被 5+ 个系统引用，但各系统升级 eds-utility 的节奏不同。
真实场景（2021 年）：
eds-web-app 升级了 eds-utility 到 v7.0.2（加了新的 ProtoBuf 消息类型）。
hedging-as 还在用 v6.6 的 eds-utility（没有新消息类型）。
某次 eds-web-app 向 hedging-as 发送了一条新类型的 ProtoBuf 消息。
hedging-as 收到后尝试反序列化——但它的 eds-utility 中没有这个类型定义。
→ ClassNotFoundException
→ 消息处理失败
→ 这条消息是"波动率参数更新"——hedging-as 没收到
业务影响：
→ hedging-as 用旧的波动率参数跑了一天的风控
→ 当天的 EOD 风控报告基于错误参数
→ 第 2 天才发现"为什么昨天风控报告和今天的不一样？"
→ 排查了半天才发现是 eds-utility 版本不一致
这就是共享库的双刃剑：
共享了代码，也共享了风险。
一个系统升级，另一个系统没升级——你就得到了一个"部分损坏"的系统。共享库变”垃圾桶”——什么都往里放
82 位贡献者在 10 年里给 eds-utility 加了各种功能。由于”放在共享库”比”放到正确的模块”更容易，eds-utility 变成了一个无所不包的集合。
后果（2022 年）：
一个开发需要修改"保证金计算的某个参数"。
他在 eds-utility 的 pbMargin/ 下找到了这个参数的常量定义。
他改了常量——但不知道这个常量还被 hedging-as 的另一个模块引用。
→ hedging-as 的 margin 计算变成了错误的值
→ 因为 eds-utility 里的一个常量被认为是"内部配置"，没想到会影响对冲引擎
追查时间：
→ 2 天后才发现是 eds-utility 的常量修改导致的
→ 修复：把那个常量移回到 hedging-as 自己的配置中
→ 但花了 2 天的时间来定位"为什么保证金突然变了"
教训：
共享库里的每一行代码，都是"有可能影响所有系统"的代码。
改之前需要想：这个改动会影响 eds-web-app 吗？hedging-as 吗？sac-report 吗？
实际上没有人每次都问这个问题——因为没人知道 eds-utility 被哪些系统引用了。框架工具积累 业务逻辑共享化 维护期
2017-2019 2020-2022 2023-2026
├── ORM 框架 ─────→ ├── ProtoBuf 通信 ─────→ ├── 低活跃
├── 加密工具 ├── ActiveMQ 消息 │ 维护模式
├── 常量定义 ├── 行情工具
│ ├── 保证金逻辑
│ └── 1,536 commits/年峰值
└────────────────── └────────────────── └───────────关键发现
- 共享库是有业务逻辑的——不仅仅是工具类，ActiveMQ、ProtoBuf、保证金相关代码都涉及核心业务
- Yuping Ai 一人 785 个 commit（19%）——和 hedging-as 一样高度依赖单一核心开发者
- 2020 年峰值与 v6.6 发布对齐——系统级大版本会带动所有关联项目的 commit 量
- 2026 年仍在更新——虽然只有 43 个 commit，但 6 月还有提交