南车电机ESB项目服务接口规范

南车电机ESB项目服务接口规范本规范基于南车电机ESB（企业服务总线）项目建设目标，为实现企业内部各业务系统（如ERP、MES、CRM、OA、生产监控系统等）的互联互通、数据共享与业务协同，明确服务接口的设计原则、技术要求、安全规范、调用规则及管理机制。本规范适用于南车电机ESB项目中所有服务接口的设计、开发、测试、部署及运维全生命周期管理，所有参与项目的开发单位、业务部门及技术人员均需严格遵照执行。一、总则（一）规范目的1.统一接口设计标准，确保各系统间接口风格一致、交互顺畅，降低系统集成复杂度。2.明确接口技术要求与安全规范，保障数据传输的安全性、完整性与可靠性。3.规范接口调用流程与异常处理机制，提升系统间协同效率，减少接口对接故障。4.为接口的开发、测试、验收及运维提供明确依据，保障ESB项目建设质量与进度。（二）适用范围1.接口类型：涵盖南车电机ESB项目中所有跨系统服务接口，包括同步接口、异步接口、查询接口、推送接口、文件传输接口等。2.参与对象：参与ESB项目接口设计、开发、测试、部署、运维的技术人员，以及各业务系统责任部门相关人员。3.业务场景：包括但不限于生产计划协同、物料管理、订单管理、质量管理、设备监控、财务核算、人力资源管理等核心业务场景的接口交互。（三）设计原则1.标准化原则：接口设计遵循行业通用标准（如SOAP、REST）及企业内部技术规范，确保接口的通用性与兼容性。2.松耦合原则：接口设计独立于具体业务系统实现，降低系统间依赖，便于各系统独立升级与维护。3.安全性原则：全面考虑数据传输、存储及访问过程中的安全风险，落实身份认证、权限控制、数据加密等安全措施。4.可靠性原则：接口需具备异常重试、容错处理、日志记录等机制，确保在网络波动、系统异常等情况下数据传输的准确性与完整性。5.高性能原则：接口设计需兼顾响应效率，优化数据传输格式与交互流程，满足高并发业务场景需求。6.可扩展性原则：接口预留扩展字段与功能节点，支持业务需求的后续迭代升级，减少接口重构成本。二、接口设计规范（一）接口命名规范1.命名规则：采用“业务域_服务类型_具体功能”的命名格式，使用英文小写字母、数字及下划线“_”组成，避免使用特殊字符。2.业务域划分：根据南车电机业务场景，业务域包括但不限于：prod（生产管理）、mat（物料管理）、order（订单管理）、quality（质量管理）、equip（设备管理）、finance（财务管理）、hr（人力资源）、oa（办公自动化）等。3.服务类型：包括query（查询）、submit（提交）、update（更新）、delete（删除）、push（推送）、sync（同步）、file（文件传输）等。4.示例：prod_query_productionPlan（生产管理-查询-生产计划）、mat_submit_materialApply（物料管理-提交-物料申请）、equip_push_equipmentStatus（设备管理-推送-设备状态）。（二）接口版本管理规范1.版本标识：采用“V+数字”的格式标识接口版本，如V1、V2，版本号从1开始递增。2.版本兼容：接口版本升级需保证向前兼容，即新版本接口需支持旧版本接口的核心功能与数据格式，避免影响已上线系统正常运行。3.版本命名：在接口名称后添加版本号，格式为“接口名称_V版本号”，示例：prod_query_productionPlan_V2。4.版本迭代：当业务需求变更导致接口功能、数据结构或调用规则发生重大调整时，需进行版本升级，并同步更新接口文档。（三）数据结构规范1.数据格式：优先采用JSON格式进行数据传输，对于复杂业务场景或传统系统对接，可兼容SOAP协议的XML格式。2.字段命名：采用英文小写字母、数字及下划线“_”组成，遵循“见名知义”原则，避免使用缩写（通用缩写除外，如id、name、code）。3.字段类型：明确各字段的数据类型，包括字符串（string）、整数（int）、浮点数（float/double）、布尔值（boolean）、日期时间（datetime）等，日期时间格式统一为“yyyy-MM-ddHH:mm:ss”。4.必选与可选：明确每个字段的必选（required）或可选（optional）属性，必选字段缺失时接口需返回错误提示。5.数据长度与约束：对字符串类型字段明确最大长度，对数值类型字段明确取值范围，避免数据溢出或格式错误。6.示例（JSON格式）：json

{

"requestHeader":{

"interfaceName":"prod_query_productionPlan_V1",

"requestId":"20240520103000123",

"timestamp":"2024-05-2010:30:00",

"appId":"MES001"

},

"requestBody":{

"planNo":"PP202405001",//生产计划编号，必选

"workshopCode":"WS01",//车间编码，可选

"startDate":"2024-05-01",//计划开始日期，必选

"endDate":"2024-05-31"//计划结束日期，必选

}

}（四）接口参数规范1.参数分类：接口参数分为请求头（requestHeader）和请求体（requestBody），请求头包含接口元数据信息，请求体包含具体业务参数。2.请求头必选参数：包括interfaceName（接口名称）、requestId（请求唯一标识，由调用方生成，确保全局唯一）、timestamp（请求时间戳）、appId（调用方系统标识，由ESB系统统一分配）、sign（签名信息，用于身份验证）。3.请求体参数：根据具体业务需求设计，需明确参数名称、类型、必选属性、说明及约束条件。4.响应参数规范：响应参数分为响应头（responseHeader）和响应体（responseBody），响应头包含响应状态、错误码、错误信息等，响应体包含具体业务响应数据。5.响应头必选参数：包括requestId（对应请求的唯一标识）、timestamp（响应时间戳）、code（响应状态码，0表示成功，非0表示失败）、message（响应信息，成功时为“success”，失败时为具体错误描述）。三、接口技术要求（一）通信协议1.优先采用HTTP/HTTPS协议进行接口通信，其中涉及敏感数据（如财务数据、个人信息、核心业务数据）的接口必须使用HTTPS协议加密传输。2.对于异步消息交互场景，采用JMS协议，基于ESB内置的消息队列实现消息的发送、接收与转发。3.对于文件传输接口，采用FTP/SFTP协议，其中敏感文件传输必须使用SFTP协议进行加密。（二）接口类型及交互模式1.同步接口：调用方发起请求后，需等待服务方响应完成才能继续后续操作，适用于需要实时获取结果的业务场景（如查询生产计划、验证物料编码）。同步接口响应时间要求：普通场景不超过3秒，复杂业务场景不超过5秒。2.异步接口：调用方发起请求后无需等待服务方响应，直接继续后续操作，服务方处理完成后通过回调接口或消息队列返回结果，适用于非实时、数据量大或耗时较长的业务场景（如批量同步生产数据、推送订单信息）。异步接口需支持消息持久化，确保消息不丢失。3.查询接口：用于获取目标系统的业务数据，调用方通过传入查询条件，服务方返回符合条件的结果集。查询接口需支持分页查询，分页参数统一为pageNum（页码，默认1）、pageSize（每页条数，默认20，最大不超过100）。4.推送接口：由服务方主动将业务数据推送到调用方接口，适用于数据实时同步场景（如设备状态变更推送、质量异常预警推送）。推送接口需支持幂等性设计，避免重复处理同一数据。（三）幂等性要求1.所有接口必须支持幂等性，即相同的请求多次提交后，服务方的处理结果一致，不会产生重复数据或异常影响。2.实现方式：通过请求头中的requestId（唯一请求标识）实现幂等性校验，服务方需记录已处理的requestId，对于重复的requestId直接返回之前的处理结果，不再重复业务逻辑处理。（四）超时与重试机制1.超时设置：同步接口默认超时时间为5秒，调用方可根据业务需求在合理范围内调整，但最大不超过10秒；异步接口默认超时时间为30秒。2.重试机制：调用方在接口调用超时或出现非业务性错误（如网络波动、系统临时不可用）时，可进行重试。重试次数默认不超过3次，重试间隔依次为1秒、3秒、5秒。对于业务性错误（如参数错误、数据不存在），不允许重试，需直接返回错误信息并由业务人员处理。四、接口安全规范（一）身份认证1.所有接口调用必须进行身份认证，调用方需在请求头中携带appId（系统唯一标识）和sign（签名），ESB系统对appId和sign进行校验，校验通过后方可转发请求。2.签名生成规则：采用“appId+timestamp+密钥+请求体”的字符串进行MD5加密（32位小写），其中密钥由ESB系统管理员为各调用系统统一分配，严格保密。3.timestamp有效期：请求头中的timestamp与ESB系统当前时间差不超过5分钟，否则视为无效请求，拒绝处理。（二）权限控制1.ESB系统建立细粒度的权限控制体系，基于角色对调用方系统进行接口权限分配，即每个appId对应一个或多个角色，每个角色仅能调用授权范围内的接口。2.权限申请与变更：调用方系统需通过正规流程向ESB项目组申请接口权限，权限变更需重新审批，ESB系统实时更新权限配置。（三）数据加密1.传输加密：采用HTTPS/SFTP协议进行数据传输加密，确保数据在传输过程中不被窃取或篡改。2.敏感数据加密：对于接口请求/响应中的敏感数据（如身份证号、银行账号、密码、核心技术参数），需在应用层进行加密处理（采用AES-256加密算法），ESB系统仅负责数据转发，不参与加密/解密过程。（四）防攻击措施1.接口限流：ESB系统对每个appId的接口调用频率进行限流控制，默认单接口每秒调用不超过10次，超出限流阈值时，ESB系统返回“429TooManyRequests”错误，调用方需进行流量控制。2.防SQL注入：服务方接口需对输入参数进行校验与过滤，避免SQL注入攻击；ESB系统对接口请求数据进行常规安全检测，拦截可疑请求。五、接口异常处理规范（一）错误码设计1.错误码采用“4位数字”编码规则，分为系统级错误码（0001-1999）和业务级错误码（2000-9999）。2.系统级错误码：0000：成功0001：请求参数错误0002：签名验证失败0003：身份认证失败（appId无效）0004：接口权限不足0005：接口调用超时0006：系统内部错误0007：请求过于频繁（限流）3.业务级错误码：由各业务域自行定义，需在接口文档中明确说明，示例：2001：生产计划编号不存在3001：物料编码无效4001：设备编号不存在（二）异常响应格式接口调用失败时，需返回统一的异常响应格式，示例（JSON格式）：json

{

"responseHeader":{

"requestId":"20240520103000123",

"timestamp":"2024-05-2010:30:03",

"code":"0001",

"message":"请求参数错误：生产计划开始日期格式不正确，正确格式为yyyy-MM-ddHH:mm:ss"

},

"responseBody":null

}（三）异常日志记录1.调用方与服务方均需记录接口调用异常日志，日志内容包括requestId、接口名称、请求参数、响应结果、错误码、错误信息、调用时间、异常发生时间等。2.ESB系统需记录所有接口的转发日志，包括请求来源、目标系统、转发状态、耗时等信息，便于问题排查与追溯。六、接口文档规范（一）文档内容要求每个接口必须编制完整的接口文档，文档内容包括：1.接口基本信息：接口名称、版本号、业务描述、适用场景、调用方式（同步/异步）、通信协议、请求地址。2.请求参数说明：请求头参数和请求体参数的名称、类型、必选属性、说明、约束条件及示例。3.响应参数说明：响应头参数和响应体参数的名称、类型、说明及示例（包括成功响应和失败响应）。4.错误码说明：接口相关的系统级错误码和业务级错误码的含义及处理建议。5.调用示例：完整的请求示例和响应示例（包括JSON/XML格式）。6.注意事项：接口调用的特殊要求、幂等性说明、超时设置、重试机制等。（二）文档管理1.接口文档采用统一的模板编制，格式为PDF或HTML，由接口开发人员负责编写，业务部门与ESB项目组审核确认。2.接口文档需在ESB项目文档管理平台集中管理，确保文档的完整性、准确性与时效性。接口版本升级时，需同步更新接口文档，并标注版本变更内容。3.接口文档需对相关开发人员、测试人员及业务人员开放查阅权限，便于对接工作开展。七、接口测试与验收规范（一）测试要求1.接口开发完成后，开发单位需进行单元测试，确保接口功能符合设计要求，通过Postman、JMeter等工具进行接口调用测试。2.测试内容包括：功能测试（正常场景、异常场景）、性能测试（响应时间、并发量）、安全测试（身份认证、权限控制、数据加密）、兼容性测试（不同系统版本、不同环境）、幂等性测试、超时重试测试。3.接口测试需覆盖所有业务场景，测试用例需经ESB项目组审核确认，测试通过率需达到100%方可提交验收。（二）验收标准1.功能验收：接口能正确响应所有正常请求，准确处理异常场景，返回结果符合接口文档要求。2.性能验收：同步接口响应时间符合要求（普通场景≤3秒，复杂场景≤5秒），异步接口消息处理延迟≤30秒，接口并发量满足业务需求（默认单接口并发≥50TPS）。3.安全验收：身份认证、权限控制、数据加密等安全措施有效，能抵御常见的安全攻击（如SQL注入、接口滥用）。4.文档验收：接口文档完整、准确，符合文档规范要求。5.兼容性验收：接口能与对接系统正常交互，无兼容性问题。八、