# 主数据接口相关问题排查指南

# 排查指南详细说明

通用前置检查：

确认版本：MDM 7.3.0
确认服务状态：MDM后端服务、AFCenter服务是否正常运行
检查网络连通性：调用方与被调用方（MDM、ESB）网络是否互通
查看接口文档：通过管理门户“服务管理”或Swagger地址（/swagger-ui.html?urls.primaryName=mdm）查看接口定义
查阅补丁列表：主数据7.3补丁列表 (opens new window)

# 场景一：OpenAPI接口调用异常

问题现象：
1. 接口调用返回404、405等HTTP状态码错误
2. 接口返回空指针、数据不存在等业务异常
3. 新增/更新接口调用后，数据未正确保存或部分字段丢失
4. 主子表接口调用时，子表数据丢失、主键冲突或报错
5. 接口调用超时或性能缓慢
6. 编码规则在接口调用时未生效
排查步骤：
1. 第一步：排除产品BUG
  - 操作：在MDM官方补丁列表中搜索关键词 接口、API、调用、OpenAPI
  - 相关补丁：
    - MDM_7.3_ALL_20251119_P1（修复根据系统主键发布业务数据接口报错）
    - MDM_7.3_SERVER_20251103_P1（增强新增接口对默认值的支持）
    - MDM_7.3_SERVER_20250925_P2（修复主子模型接口调用子模型找不到key问题）
    - MDM_7.3_SERVER_20250928_P2（修复主子模型导入空指针，需重新下载模板）
    - MDM_7.3_SERVER_20250930_P1（批量新增接口支持）
    - MDM_7.3_SERVER_20251015_P1（修复编码规则在新增并生效接口中未生成问题）
    - MDM_7.3_SERVER_20260202_P1（JPA事务优化及数据库连接池断开问题）
  - 解决方案：若找到描述匹配的补丁，则申请并应用
2. 第二步：根据问题现象排查
  - 现象：接口404/405错误
    - 排查项：请求URL、HTTP方法是否与接口文档一致
    - 排查项：URL路径中的{dataModelCode}是否替换为实际的模型编码（注意大小写）
    - 排查项：API版本路径（如/api/mdm/openapi/）是否正确
    - 解决方案：
      - 根据接口文档修正请求URL和方法
      - 确认模型编码与系统中定义的完全一致
  - 现象：接口返回业务异常（空指针、数据不存在）
    - 排查项：请求参数中是否包含必要的业务主键或M_ID
    - 排查项：对于更新操作，要更新的数据是否存在
    - 排查项：请求体中字段名称是否与模型字段编码完全一致
    - 解决方案：
      - 确保请求参数完整且正确
      - 对于主子表更新，需传入子表数据的M_ID
      - 申请补丁解决已知接口问题
  - 现象：主子表接口调用异常
    - 排查项：请求体中主子表数据的JSON嵌套结构是否正确
    - 排查项：子表数据中是否包含必要的关联字段
    - 排查项：
      - 新增操作：子表数据的主键（M_ID）是否重复，或由系统自动生成
      - 更新操作：是否传入了子表数据的M_ID
    - 解决方案：
      - 参考接口文档中主子表请求示例调整报文结构
      - 新增时：确保子表主键唯一，或由系统自动生成
      - 更新时：需传入子表数据的M_ID，否则会覆盖或新增子表数据
      - 申请补丁：
        MDM_7.3_SERVER_20250925_P2（修复子模型找不到key问题）
        
        MDM_7.3_SERVER_20250928_P2（修复主子模型导入空指针）
  - 现象：编码规则未生效
    - 排查项：模型中是否已配置编码方案并发布
    - 排查项：调用的是新增接口还是新增并生效接口
    - 解决方案：
      - 确保编码方案已配置并发布
      - 申请补丁 MDM_7.3_SERVER_20251015_P1
  - 现象：接口调用超时
    - 排查项：单次请求的数据量是否过大（如批量新增大量数据）
    - 排查项：数据库性能是否存在瓶颈
    - 解决方案：
      - 减少单次请求的数据量，分批处理
      - 检查数据库连接池配置和性能
      - 申请补丁 MDM_7.3_SERVER_20260202_P1

# 场景二：服务注册/ESB集成异常

问题现象：
1. 服务注册到ESB失败，或注册后状态显示不正确
2. 注册的服务在ESB平台无法调用
3. 通过ESB调用MDM接口时报错
4. 服务取消注册失败
排查步骤：
1. 第一步：排除产品BUG
  - 操作：搜索关键词 注册、ESB、服务
  - 相关补丁：
    - MDM_7.3_SERVER_20251204_P2（优化注册服务提示，单条接口注册前需先执行全量注册）
  - 解决方案：若找到描述匹配的补丁，则申请并应用
2. 第二步：根据问题现象排查
  - 现象：服务注册失败
    - 排查项：application-mdm.properties中ESB相关配置是否正确
      # ESB9.0/iPaaS 9.1.0版本需设置为true mdm.esb.support.afc=true
    - 排查项：在ESB平台上是否已提前注册好相关的域、系统、通道信息
    - 排查项：注册时选择的域、系统、通道是否与ESB平台一致
    - 解决方案：
      - 修正配置文件后重启服务
      - 先在ESB平台完成域、系统、通道的注册，再执行MDM服务注册操作
      - 先执行一次全量注册，再进行单条接口注册
  - 现象：注册后服务无法调用
    - 排查项：在ESB平台检查服务的发布状态
    - 排查项：ESB平台的路由配置是否正确
    - 解决方案：
      - 在ESB平台手动发布服务
      - 检查ESB路由规则，确保请求能正确转发到MDM后端
  - 现象：服务取消注册失败
    - 排查项：是否有正在运行的流程或依赖该服务
    - 解决方案：在ESB平台手动删除服务注册信息

# 场景三：客户端/服务授权异常

问题现象：
1. 接口调用返回401 Unauthorized或403 Forbidden
2. 新增客户端后，调用接口提示凭证无效
3. 客户端有权限，但调用某些接口时提示无权限
4. 更换访问凭证后，旧凭证仍然可用
排查步骤：
1. 第一步：排除产品BUG
  - 操作：搜索关键词 客户端、授权、凭证
  - 相关补丁：
    - MDM_7.3_UI_20260302_P2（修复服务授权编辑时模型名不显示中文）
    - MDM_7.3_UI_20251117_P1（优化数据授权页面，修复子模型字段选择问题）
  - 解决方案：若找到描述匹配的补丁，则申请并应用
2. 第二步：根据问题现象排查
  - 现象：接口返回401/403
    - 排查项：请求头中是否包含正确的客户端凭证
      # 方式一：专用请求头 x-mdm-client-code: {CLIENT_CODE} x-mdm-client-secret: {CLIENT_SECRET} # 方式二：Basic认证 Authorization: Basic {BASE64(CLIENT_CODE:CLIENT_SECRET)}
    - 排查项：客户端凭证未过期，且状态为“启用”
    - 排查项：在“服务授权”中，该客户端是否已授权给目标模型
    - 解决方案：
      - 修正请求头中的凭证信息
      - 在客户端管理中重新生成凭证或启用客户端
      - 在“服务授权”中为客户端配置模型权限
  - 现象：部分接口无权限
    - 排查项：在“服务授权”中，该模型的“OpenAPI服务权限”是否勾选了所有需要调用的接口
    - 解决方案：在服务授权中，勾选对应的API权限后保存
  - 现象：更换凭证后旧凭证仍可用
    - 排查项：更换凭证时，是否设置了“新凭证失效时刻”
    - 解决方案：更换凭证时，选择旧凭证立即失效

# 场景四：接口报文/加密异常

问题现象：
1. 接口调用返回报文解析失败
2. 启用加密传输后，客户端无法解密响应数据
3. 启用GZIP压缩后，数据解压失败
4. 请求报文中的特殊字符导致解析错误
排查步骤：
1. 第一步：排除产品BUG
  - 操作：搜索关键词 报文、加密、解密、压缩
  - 相关补丁：
    - MDM_7.3_SERVER_20251229_P1（优化between查询容错机制）
    - MDM_7.3_SERVER_20260127_P1（修复非http方式调用时空指针问题）
    - MDM_7.3_ALL_20251120_P1（限制输入和导入带有英文“/”）
  - 解决方案：若找到描述匹配的补丁，则申请并应用
2. 第二步：根据问题现象排查
  - 现象：加密传输解密失败
    - 排查项：客户端配置的密钥与MDM中配置的密钥是否一致
    - 排查项：解密时使用的密钥类型是否正确（公钥/私钥）
    - 排查项：如果启用了GZIP压缩，解压和解密的顺序是否正确（先解压后解密）
    - 解决方案：
      - 在客户端管理中重新生成密钥对，确保私钥已保存
      - 参考RSA加解密工具类示例调整解密代码
      - 如需申请加密相关的jar包：通过AME+发起工单
  - 现象：报文中的特殊字符导致解析错误
    - 排查项：字典项或字段值中是否包含“/”、“&”等特殊字符
    - 解决方案：申请补丁 MDM_7.3_ALL_20251120_P1
  - 现象：响应报文格式与预期不符
    - 排查项：请求头中的Accept字段是否设置正确
      Accept: application/json # 明文响应 Accept: application/octet-stream # 密文响应
    - 解决方案：根据需求设置正确的Accept头

# 场景五：统一服务代理（扩展）接口异常

问题现象：
1. 调用代理接口时，提示“action”参数错误或无效
2. 通过代理接口调用时，参数传递方式不正确导致失败
3. 代理接口返回的结果与直接调用接口不一致
4. 请求体中的查询条件未生效
排查步骤：
1. 第一步：排除产品BUG
  - 操作：搜索关键词 代理、action、统一接口
  - 相关补丁：目前无直接相关补丁
  - 解决方案：如确认是产品缺陷，通过AME+发起工单反馈
2. 第二步：确认接口调用方式
  - API-27 (GET方式)：适用于无请求体的调用，所有参数通过URL传递
```
GET /api/mdm/openapi?action=2&dataModelCode=school_student&pageIndex=0&pageSize=10
```
    - action=2：表示调用查询接口（接口编号可通过服务列表查看）
    - 原接口路径上的参数（如dataModelCode）改为查询参数传递
  - API-28 (POST方式)：适用于有请求体的调用，查询条件放在请求体中
```
POST /api/mdm/openapi?action=2&dataModelCode=school_student&pageIndex=0&pageSize=10
Content-Type: application/json

{
  "args": [
    {"name": "gender", "matchValue": "M"},
    {"name": "name", "matchType": "starts_with", "matchValue": "上官"}
  ]
}
```
    - 查询条件通过args数组传递
    - 每个条件包含name（字段名）、matchType（匹配类型）、matchValue（匹配值）
3. 第三步：根据问题现象排查
  - 现象：action参数错误
    - 排查项：action参数值是否为有效的接口编号
    - 排查项：可通过“服务管理”页面或Swagger文档查看各接口对应的编号
    - 解决方案：使用正确的接口编号，常见接口编号：
      - action=2：查询接口
      - action=3：新增接口
      - action=4：更新接口
      - action=12：根据业务主键更新并生效接口
  - 现象：参数传递错误
    - 排查项：原接口路径上的参数（如dataModelCode、id等）是否已改为URL查询参数传递
    - 排查项：对于GET方式调用，所有参数必须放在URL中
    - 解决方案：
      - 将所有路径参数改为查询参数，放在URL中传递
      - 例如：原接口/api/mdm/openapi/school_student/query改为?action=2&dataModelCode=school_student
  - 现象：查询条件未生效
    - 排查项：对于POST方式调用，请求体中的args数组格式是否正确
    - 排查项：每个查询条件的name、matchType、matchValue字段填写是否正确
    - 排查项：matchType支持的取值：
      - eq：等于
      - like：模糊匹配
      - gt：大于
      - lt：小于
      - starts_with：以...开头
      - ends_with：以...结尾
    - 解决方案：
      - 参考接口文档中的查询条件格式调整请求体
      - 确保matchType使用正确的枚举值