# 跨模块集成与调用安全 (Integration Safety)

为避免因**参数顺序错误**、**类型不匹配**或**接口契约理解偏差**导致的缺陷，在跨模块调用（跨层、跨包、跨服务边界）时请遵守以下规则。

## 1. 强制核对签名 (Mandatory signature verification)

- **调用前先看定义**：编写或修改调用其他模块函数的代码前，**必须**用 Read / 跳转定义打开**目标函数源码**，核对参数列表与默认值。
- **核对参数顺序**：禁止凭记忆或 IDE 片段猜测。对多个同类型参数（如多个 `string` / `object`）要逐一对应。
- **关注可选参数**：是否可选、默认值、是否会在运行时 `undefined` 导致分支变化。

## 2. 数据模型与契约一致 (Model alignment)

- **分清载体**：区分数据在 **Request body**、**query**、**headers**、**path** 中的归属；代理或转发时不要混放。
- **字段最小化**：向下游发送的 payload 应**只包含**对方契约声明的字段；多余字段可能触发校验失败或隐蔽行为差异。
- **有 Schema 优先**：若存在 Joi / Zod / OpenAPI 等定义，**以 Schema 为准**，不要凭接口名猜字段名。

## 3. 日志辅助验证 (Log-based validation)

- 在复杂集成路径上，可在入口/出口对**关键参数**打日志（注意脱敏）。
- 遇到「参数错误」「校验失败」等模糊报错时，用日志对比**实际发出的结构与预期模型**是否一致。

## 4. 典型反例

- **参数位置写反**：例如 `(ctx, id, body)` 写成 `(ctx, body, id)`。
- **载体混淆**：把本应在 JSON body 里的对象序列化进 query，或反之。
- **加解密/编解码假设错误**：未确认下游期望的是明文还是某种编码后的字符串。