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

排查指南详细说明

通用前置检查：

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

---

场景一：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（修复编码规则在新增并生效接口中未生成问题）
     • 解决方案：
       • 1.优先使用产品最新补丁合集，见补丁列表中补丁合集列表
       • 2.若找到描述匹配的补丁，则申请并应用

  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（优化注册服务提示，单条接口注册前需先执行全量注册）
     • 解决方案：
       • 1.优先使用产品最新补丁合集，见补丁列表中补丁合集列表
       • 2.若找到描述匹配的补丁，则申请并应用

  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（优化数据授权页面，修复子模型字段选择问题）
     • 解决方案：
       • 1.优先使用产品最新补丁合集，见补丁列表中补丁合集列表
       • 2.若找到描述匹配的补丁，则申请并应用

  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（限制输入和导入带有英文“/”）
     • 解决方案：
       • 1.优先使用产品最新补丁合集，见补丁列表中补丁合集列表
       • 2.若找到描述匹配的补丁，则申请并应用

  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、统一接口
     • 解决方案：
       • 1.优先使用产品最新补丁合集，见补丁列表中补丁合集列表
       • 2.若找到描述匹配的补丁，则申请并应用

  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使用正确的枚举值