金融行业科技部开发员接口文档编写手册（执行版）

金融行业科技部开发员接口文档编写手册（执行版）1总则1.1编写目的为统一金融科技部各类系统接口文档的编写标准、格式规范与内容要求，规范前后端开发、跨系统对接、联调测试、运维排查及外部合作对接全流程工作，保障金融接口的安全性、合规性、准确性、可追溯性，规避接口不规范导致的交易异常、数据泄露、对接故障、监管合规风险，提升系统迭代、问题排查效率，特制定本执行手册。本手册为科技部接口文档编写、审核、更新、归档的唯一执行标准，所有接口开发相关人员必须严格遵照执行。1.2适用范围本手册适用于金融科技部所有自研系统、外包开发系统、第三方对接系统的接口文档编写工作，涵盖HTTP/HTTPS接口、RPC接口、WebService接口、文件传输接口、消息队列接口等所有类型业务与技术接口。适用人员：科技部开发工程师、接口联调测试人员、技术负责人、运维人员、外部合作对接开发人员。适用场景：新接口开发上线、存量接口迭代变更、接口下线、跨部门/跨机构系统对接、故障复盘追溯、系统运维支撑、监管资料报备。1.3合规与标准依据本手册编写严格遵循国家、行业及公司内部规范，核心依据如下：GB/T36576-2018《金融信息系统接口通用规范》ISO20022金融报文传输标准金融行业网络安全等级保护2.0相关规范公司信息系统开发管理规范、数据安全管理办法金融API网关（FAPIGateway）接入规范1.4核心编写原则合规优先：严格遵守金融数据安全、交易合规要求，敏感字段、接口权限、报文加密等内容必须完整标注，杜绝合规漏洞。真实准确：所有接口路径、参数、规则、示例、错误码必须与实际代码一致，禁止虚构、滞后更新内容。完整全面：覆盖接口功能、权限、参数、异常、安全、依赖、限流、重试等所有对接关键信息，无遗漏项。简洁规范：格式统一、语言专业通俗、结构清晰，便于开发、测试、运维快速查阅使用。动态可追溯：接口变更必须同步更新文档，留存版本记录与变更说明，全程可追溯。2文档基础规范2.1文档版本规范所有接口文档必须标注版本信息，采用主版本.次版本.修订版本三段式版本号（如V1.2.0），版本迭代规则如下：主版本（Vx.0.0）：接口核心功能、请求响应结构、权限规则重大变更，不兼容旧版本。次版本（V1.x.0）：新增接口、新增可选参数、优化接口逻辑，向下兼容旧版本。修订版本（V1.2.x）：修复文档描述错误、补充示例、优化注释，接口功能无变更。文档头部必须固定包含：文档名称、版本、编写人、审核人、编写日期、更新日期、适用系统。2.2格式统一规范结构层级：统一采用二级、三级、四级标题分层，层级清晰，禁止混乱排版。参数说明：统一使用表格展示，包含字段名称、字段类型、是否必填、长度限制、描述、枚举值、敏感等级。代码示例：请求、响应报文统一使用对应格式代码块（JSON/XML），格式规整、可直接复制调试。术语统一：金融交易、数据字段、状态码、错误提示严格沿用公司统一术语，禁止自定义表述。2.3文档生命周期管理新建：接口开发完成、联调前必须完成文档编写，未完成文档编写的接口禁止提测、上线。更新：接口任何参数、逻辑、权限、错误码变更，必须在24小时内同步更新文档，标注变更内容与原因。归档：接口上线后，文档统一归档至公司知识库，分类存储，权限可控。下线：接口下线后，文档标注下线时间、下线原因，保留归档记录，禁止直接删除。3接口文档标准结构（强制执行）所有接口文档必须包含以下10个核心模块，缺一不可，模块顺序固定，不得随意删减调整。3.1文档概述用于说明整体文档覆盖范围与基础信息，核心包含4项内容：文档简介：简要说明本文档覆盖的接口模块、业务场景（如用户开户、资金划转、交易查询、对账文件传输等）。系统信息：对接系统名称、系统归属、部署环境（测试/预生产/生产）、网关地址。依赖说明：本模块接口依赖的上游服务、下游接口、中间件、数据库版本。适配说明：适配的API网关版本、报文标准、加密协议版本。3.2通用基础规则统一模块内所有接口的公共规则，避免重复描述，为对接提供统一标准：请求协议：明确统一请求协议（HTTP/HTTPS/RPC）、请求端口、编码格式（统一UTF-8）。认证授权：详细说明接口鉴权方式（Token、密钥、签名、白名单）、Token有效期、签名算法、密钥获取方式、权限控制粒度。数据加密规则：金融敏感数据（手机号、身份证、银行卡、交易密码）的加密算法、脱敏规则、传输加密要求。通用请求头/响应头：列出所有接口公共请求头（时间戳、设备号、渠道号）、响应头参数及含义。限流与超时规则：单接口QPS上限、单次请求超时时间、限流触发策略、熔断机制。重试机制：失败重试次数、重试间隔、可重试异常场景、禁止重试场景（避免重复交易）。时间格式规范：统一时间字段格式（如yyyy-MM-ddHH:mm:ss）、时区（统一北京时间）。3.3接口清单汇总以表格形式汇总本模块所有接口，实现快速检索，表格字段固定：接口名称、接口路径、请求方式、接口功能、业务场景、状态（开发中/已上线/已下线）、备注。3.4单接口详细说明（核心模块）每个接口独立编写详情，严格包含以下固定子模块，内容详实、精准：3.4.1接口基础信息接口名称、唯一接口ID、请求URL、请求方式（GET/POST/PUT/DELETE）、接口版本、业务优先级（核心交易/普通查询）、接口用途、适用场景。3.4.2请求参数详情分路径参数、查询参数、请求体参数三类分别说明，统一表格呈现，必填项严格标注：字段名称：与代码字段名完全一致，区分大小写字段类型：String/Int/Long/Decimal/Boolean等精准标注，金融金额字段必须标注精度（如Decimal(16,2)）是否必填：必选/可选，核心交易参数禁止模糊标注长度限制：明确最大、最小长度，数值字段标注取值范围字段描述：清晰说明字段业务含义，金融关键字段需补充业务规则枚举值：固定取值的字段，列出全部枚举值及对应业务含义敏感等级：普通/一般敏感/高度敏感，明确加密、脱敏要求3.4.3请求示例提供可直接调试的完整请求示例，包含完整请求头、参数、报文，覆盖正常业务场景，核心交易接口需补充特殊场景示例。禁止空示例、虚假示例。3.4.4响应参数详情格式与请求参数表格一致，区分全局响应字段、业务数据字段，针对嵌套结构，需分层说明，明确空值返回规则、分页返回规则。金融交易结果、对账字段必须重点标注。3.4.5响应示例提供成功响应、常规失败响应完整报文示例，格式规整，与实际接口返回完全一致，包含所有默认返回字段。3.4.6业务规则说明金融接口核心必填模块，详细说明接口专属业务逻辑：交易校验规则、状态流转规则、资金计算规则、数据唯一性校验、幂等性规则、重复请求处理逻辑、跨系统联动规则。其中所有交易类接口必须明确幂等实现方式与校验规则。3.5错误码与异常处理统一汇总本模块接口所有错误码，区分系统通用错误码、业务自定义错误码，表格包含：错误码、错误信息、异常原因、触发场景、处理方案、优先级。核心要求：金融交易失败、余额不足、权限不足、参数非法、超时、重复交易等关键异常必须全覆盖，明确用户侧、开发侧、运维侧处理方式。3.6安全规范说明针对金融接口安全要求专项说明，杜绝安全风险：权限控制：接口访问角色、权限范围、禁止访问场景数据安全：敏感字段传输、存储、展示脱敏规则防攻击规则：防重放、防篡改、防暴力破解、SQL注入防护说明日志规范：接口访问日志、交易日志、异常日志留存时长与记录粒度3.7接口依赖与兼容性服务依赖：接口调用依赖的第三方服务、内部微服务、数据库、缓存版本兼容：当前版本与历史版本兼容情况，不兼容变更点说明环境差异：测试、预生产、生产环境的接口地址、参数差异说明3.8测试要点说明为测试联调提供明确依据，包含：核心测试场景、边界值测试点、异常测试点、性能测试指标（响应时间、并发量）、联调注意事项。3.9变更日志逐条记录文档所有变更，表格字段：变更版本、变更时间、变更人、变更内容、变更原因、影响范围、审核人。所有变更必须可追溯、可核查。3.10附则说明文档生效时间、解释权限、违规考核标准、更新迭代规则。4各类接口专项编写要求4.1交易类接口（核心重点）适用于资金划转、充值、提现、扣款、对账等金融交易接口，额外强制要求：必须详细标注幂等性规则、交易唯一标识、重复交易处理逻辑明确交易成功、失败、超时、未知四种状态的流转规则与兜底方案精准标注金额字段精度、手续费计算规则、汇率换算规则补充交易流水生成规则、对账字段对应关系明确异常交易冲正、回滚机制4.2查询类接口必须明确分页规则、排序规则、最大查询条数限制标注数据缓存策略、数据更新延迟时间明确敏感数据查询权限、脱敏展示规则4.3文件传输接口明确文件格式、编码、大小限制、传输协议（SFTP/HTTP）标注文件命名规则、文件校验方式（MD5/SHA256）说明文件上传、下载、删除、过期清理规则对账文件需明确字段映射、生成时间、接收时效要求4.4消息队列接口明确Topic名称、消息投递方式、消费分组说明消息重试、死信队列处理规则、消息丢失兜底方案标注消息报文格式、字段校验规则、投递时序要求5审核与验收标准5.1编写自查标准开发人员完成文档后，必须完成自查，满足以下标准方可提交审核：结构完整，无缺失核心模块，格式完全符合本手册规范所有参数、规则、示例与实际代码、接口运行效果完全一致金融合规、数据安全、权限规则、异常处理无遗漏、无错误语言简洁准确，无歧义、无错别字、无逻辑漏洞变更日志完整，版本迭代清晰可追溯5.2审核流程自测提交：开发人员编写完成，自查无误后提交技术负责人审核技术审核：技术负责人校验文档准确性、完整性、合规性、规范性合规复核：核心交易接口需经合规、安全岗复核安全与合规性归档生效：审核通过后统一归档，正式生效，作为对接、运维唯一依据5.3不合格判定规则出现以下任意情况，文档直接驳回重写：核心模块缺失、结构混乱、格式不统一参数错误、示例虚假、业务规则与实际代码不符交易接口未标注幂等、冲