# API与接口调用相关问题排查指南
# 一、前置操作：补丁更新
在开始排查问题前，请务必完成以下补丁更新步骤，以排除已知问题的干扰：
- 前端： 优先安装最新的前端补丁
- 后端： 优先建议安装后端合集补丁，若无合集补丁通过以下链接检查是否存在相关补丁。若存在，请先安装对应补丁再进行后续问题排查
补丁参考链接：http://help.primeton.com/productcs/patches/
# 二、问题排查
# 1. 接口返回 404 (Not Found)
典型表现：请求状态码为404，提示“Not Found”。
排查步骤：
检查接口地址：确认请求的URL路径是否正确（注意大小写）。使用Postman等工具直接调用：
- Postman也返回404 → 后端接口问题，请对照Swagger查看接口定义和参数说明
- Postman正常 → 前端或网络代理问题，请从Nginx等方面排查
核对资源标识：确认以下参数是否正确，并确保对应资源在数据库中存在：
appName（应用名称）entityName（实体编码）formCode（表单标识）- 数据主键ID
attachmentId（附件ID）
检查代理配置：如使用Nginx等反向代理，检查配置是否正确，确保请求路径未被错误截断或重写。
# 2. 接口返回 500 (Internal Server Error)
典型表现：请求状态码为500，服务器内部错误。
排查步骤：
查看后端日志：检查服务器后台日志eos-trace.log，定位具体异常信息（如空指针、SQL语法错误）。
检查参数类型：
- 确认参数类型与接口定义匹配（如主键是
int类型时，不要传递字符串） - 时间格式：调用流程相关接口（如
startProcessInstanceWithBizInfo）时，时间格式必须严格为yyyyMMddHHmmss
- 确认参数类型与接口定义匹配（如主键是
检查数据完整性：某些操作依赖关联表数据，如人员选择器依赖
afc_employee表，若主表有数据而关联表无数据可能引发异常。
# 3. 参数传递错误
典型表现：接口返回数据不正确、查询条件未生效、或报错“参数缺失/类型错误”。
排查步骤：
处理特殊字符：参数值中的空格可能导致截断（如
Bearer xxxx-xxxx）。建议在接收参数的页面定义同名参数接收，或对参数进行编码。序列化复杂对象：传递JSON对象（如表单数据
formData）时，使用JSON.stringify()进行转换。核对必填参数：对照接口文档或Swagger定义，确认所有必填参数均已传递。
检查数据格式：对于
getPdf等打印接口，formData参数必须是JSON字符串，且templateCode（模板编码）必须正确。
# 4. 调用失败（无响应/超时/卡死）
典型表现：页面一直Loading、请求长时间无响应、或浏览器无反应。
排查步骤：
排查异步处理：在表单或视图事件中使用
await时，确保其所在函数标记为async，否则会报错中断执行。检查死循环：检查事件回调（如
valueChange）中是否触发了新接口调用，而新调用又再次触发同一事件。检查网络拦截：确认是否配置了接口黑名单，导致内网或特定IP无法访问关键接口（如
call-method）。优化性能：
- 检查是否存在频繁调用的接口（如人员机构组件鼠标移入移出触发请求），确认是否安装了相关优化补丁（最新的前端补丁）
- 检查查询是否未加分页，一次性加载过多数据导致超时
理解事务机制：附件删除和表单保存是两个独立事务。若未点击保存直接关闭弹窗，可能导致界面显示已删除但实际文件未删除。
# 三、常用工具与文档
| 工具/文档 | 用途 | 地址 |
|---|---|---|
| 浏览器开发者工具 (F12) | Network面板：查看请求URL、状态码、请求头、请求体、响应内容 Console面板：查看JavaScript报错信息 | - |
| Swagger接口文档 | 查阅标准接口定义和参数说明 | http://ip:port后端端口/swagger-ui.html |
| Help官方文档 | 组件配置说明、API用法、已知问题解决方案 | 表单组件说明文档 (opens new window) API文档说明 (opens new window) |
| 日志分析 | 查看异常堆栈信息 | 服务器后台日志文件：eos-trace.log |