金融行业外资行科技部API接口开发手册.docxVIP

金融行业外资行科技部API接口开发手册

第1章总则与基础规范

1.1接口定义与版本管理

1.1.1接口定义遵循RESTful风格设计，采用HTTP协议标准，明确定义所有业务交互的语义，确保跨语言、跨系统的调用一致性。

接口命名严格遵循命名空间规则，使用`api/v1/`前缀标识版本，业务模块名使用小写连字符分隔（如`user-service-login`），禁止使用中文或特殊符号。所有接口必须包含`Oauth2.0`标准的鉴权头，通过`Authorization`字段携带`Bearer`令牌，并在请求头中指定`Content-Type:application/json`以明确数据格式。

接口路径采用绝对路径形式，例如`/api/v1/users/profile/get`，避免使用相对路径，确保在分布式网关环境中调用时不出现路径解析错误。参数定义必须明确区分必填项与选填项，通过`required`标志位标识，并在参数描述中说明参数的业务含义、数据类型及单位，防止因参数缺失导致调用失败。接口返回结果必须包含统一的状态码，成功状态码为`200`，失败状态码需区分业务错误（如`400`）和系统错误（如`500`），并在响应体中提供详细的错误描述文本。

接口文档应包含完整的Swagger/OpenAPI3.0规范，明