一单位一平台

主题

HzTech2026-01-04
5589
22.9m

接口管理接口文档 ​

概述 ​

接口管理模块提供了子应用向一单位一平台上报接口元数据,并通过一单位一平台网关统一调用的完整解决方案。子应用首先向一单位一平台注册接口元数据(包括接口路径、请求方法、权限配置、速率限制等),然后调用方(一单位一平台或其他子应用)通过一单位一平台网关调用这些已注册的接口。网关提供路由转发、身份认证、权限控制、速率限制、日志记录等功能,实现统一的管理和监控。所有接口遵循国密 SM2/SM4 数字信封加密方案,确保数据传输安全。

交互方向 ​

本模块包含以下交互方向:

交互方向接口类型子应用实现要求说明
子应用→一单位一平台(上报)创建接口、更新接口、删除接口、查询接口详情、接口列表查询❌ 无需实现子应用主动上报/查询接口元数据,一单位一平台提供接口
调用方→一单位一平台网关→子应用通过网关调用子应用已注册的接口❌ 无需实现调用方通过网关调用子应用接口

重要说明:

  • 本模块所有接口均为"子应用→一单位一平台"上报/查询接口,子应用直接调用一单位一平台提供的接口,无需额外实现
  • 网关调用流程:调用方→一单位一平台网关→子应用,网关负责路由转发和权限控制

使用场景 ​

接口注册阶段 ​

  • 子应用 → 一单位一平台：子应用向一单位一平台上报新接口配置
  • 子应用 → 一单位一平台：子应用向一单位一平台上报接口更新
  • 子应用 → 一单位一平台：子应用向一单位一平台上报接口删除
  • 子应用 → 一单位一平台：子应用向一单位一平台查询接口信息
  • 接口同步：子应用通过接口列表查询定期同步一单位一平台的接口数据

接口调用阶段 ​

  • 调用方 → 一单位一平台网关 → 子应用：调用方通过一单位一平台网关调用子应用接口
  • 一单位一平台网关：根据接口元数据进行路由、鉴权、限流、日志记录等处理
  • 统一管理：通过网关实现所有接口的统一调用、监控和审计

接口设计原则 ​

所有接口均采用国密 SM2/SM4 数字信封加密方案:

  1. 统一 POST 方式：所有接口使用 POST 方法，业务参数在 encryptData 中加密传输
  2. 无路径参数：URL 路径中不包含任何业务参数（如 apiId），所有业务参数均在加密报文中
  3. 安全性：通过 SM2 混合加密和数字签名确保数据传输的机密性、完整性和不可抵赖性
  4. 调用封装：网关调用统一使用 POST 封装加密请求，实际业务方法以 apiMethod 元数据为准

适用范围 ​

适用于子应用向一单位一平台上报和管理接口元数据的场景。

术语定义 ​

核心概念 ​

术语说明
一单位一平台核心管理平台,负责数据存储、权限管理、接口路由等核心功能
子应用接入一单位一平台的独立业务系统,通过一单位一平台网关与其他系统交互
网关一单位一平台的统一入口,负责路由转发、身份认证、权限控制、速率限制等
调用方发起接口调用的系统,可以是一单位一平台或任意子应用

操作语义 ​

术语说明数据流向接口实现方
查询主动请求获取数据子应用→一单位一平台一单位一平台实现
上报主动提交业务数据子应用→一单位一平台一单位一平台实现

重要提示:

  • "查询"表示子应用主动向一单位一平台请求数据,由一单位一平台提供查询接口
  • "上报"表示子应用主动向一单位一平台提交数据,由一单位一平台提供接收接口

系统架构 ​

数据流向 ​

上报流程(子应用→一单位一平台) ​

子应用 → [加密上报] → 一单位一平台 → [加密响应] → 子应用

网关调用流程(调用方→一单位一平台网关→子应用) ​

调用方 → [加密请求] → 一单位一平台网关 → [路由/鉴权] → 子应用 → [加密响应] → 网关 → 调用方

接口列表 ​

子应用→一单位一平台(上报接口) ​

接口名称请求地址交互方向说明
创建接口POST /hztech-interface/api子→主(上报)上报新接口
更新接口POST /hztech-interface/api/update子→主(上报)上报接口更新
删除接口POST /hztech-interface/api/delete子→主(上报)上报接口删除
查询接口详情POST /hztech-interface/api/detail子→主(查询)获取单个接口
接口列表查询POST /hztech-interface/api/list子→主(查询)分页查询接口列表

注: 所有业务参数均在 encryptData 中加密传输，URL 路径中不包含任何业务参数。

接口调用流程 ​

完整流程说明 ​

子应用上报接口元数据后，调用方（一单位一平台或其他子应用）通过一单位一平台网关统一调用这些接口。完整流程如下：

网关功能 ​

一单位一平台网关提供以下核心功能：

功能说明
路由转发根据 apiCode 或 apiPath 将请求路由到对应的子应用服务
身份认证验证调用方身份（SM2签名验证）
权限控制根据接口元数据中的权限配置，检查调用方是否有权访问
速率限制根据接口元数据中的 rateLimit 配置，进行流量控制
日志记录记录接口调用日志（调用方、调用时间、响应时间、状态码等）
加密解密统一处理 SM2/SM4 加密解密，降低子应用接入成本

接口调用 ​

调用方（一单位一平台或其他子应用）通过一单位一平台网关调用已注册的接口。

接口说明

通过一单位一平台网关调用子应用接口。

请求方式

统一使用 POST 发送加密报文，实际业务方法以 apiMethod 为准

请求地址

POST /gateway/{apiCode}

交互方向

调用方 → 一单位一平台网关 → 子应用服务

请求示例

假设子应用已上报接口元数据：

  • apiCode: user:list
  • apiPath: /api/user/list
  • apiMethod: GET

调用方通过网关使用 POST 封装调用该接口：

http
POST /gateway/api/user/list HTTP/1.1
Host: gateway.example.com
Content-Type: application/json

{
  "appId": "CALLER_SYSTEM",
  "version": "1.0",
  "timestamp": 1735516800000,
  "nonce": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "encryptKey": "MIIBOgIBAAJBAKj34GkxFhD90vcNLYLInFEX6...",
  "encryptData": "U2FsdGVkX1+jmZn5KqWYEgjPkQKpH5KqWYEg...",
  "sign": "MEUCIQDZ5KqWYEgjPkQKpH5KqWYEgjPkQKpH5KqWY..."
}

encryptData 解密后的业务数据

json
{
  "pageNum": 1,
  "pageSize": 20,
  "filters": {
    "status": 1
  }
}

HTTP 响应示例

json
{
  "code": 200,
  "message": "success",
  "data": {
    "total": 100,
    "list": [
      {
        "id": "1123598821738675203",
        "account": "manager",
        "realName": "经理",
        "email": "ma****@hztech.vip"
      }
    ]
  },
  "timestamp": 1735516801200
}

网关错误响应示例

json
{
  "code": 2301,
  "message": "接口不存在或未注册",
  "timestamp": 1735516801000
}
json
{
  "code": 2307,
  "message": "无权限访问该接口",
  "timestamp": 1735516801000
}

调用要点 ​

  1. 接口必须先注册：子应用必须先通过"创建接口"接口上报元数据，网关才能路由
  2. 使用统一的加密协议：所有调用必须遵循国密 SM2/SM4 数字信封加密方案
  3. 权限控制：网关会根据接口元数据的权限配置进行鉴权
  4. 速率限制：超过接口配置的速率限制时，网关会拒绝请求
  5. 日志审计：所有调用都会记录日志，便于问题追踪和审计

接口详情 ​

1.1 创建接口 ​

接口说明

创建新的接口元数据。子应用向一单位一平台上报新接口配置。用于注册和管理系统的所有 API 接口。

请求方式

POST

请求地址

POST /hztech-interface/api

交互方向

子应用 → 一单位一平台 (上报)

完整时序图

请求参数

参数名类型必填说明示例值
apiNameString是接口名称"查询用户列表"
apiCodeString是接口编码(唯一)"user:list"
apiMethodString是接口请求方法"GET"
apiPathString是接口地址"/api/user/list"
requestParamsMap否接口参数说明见下方参数说明表
responseParamsMap否接口返回值说明见下方返回值说明表
descriptionString否接口描述"分页查询用户列表"
rateLimitInteger否速率限制(每秒请求数)1000
statusInteger否是否上架(1:已上架,0:未上架)0

requestParams 参数说明示例

参数名类型必填说明示例值
pageNumInteger是页码1
pageSizeInteger是每页数量20

responseParams 返回值说明示例

字段名类型说明
totalInteger总记录数
listArray用户列表
└─ idString用户ID
└─ accountString账号
└─ realNameString姓名

HTTP 请求示例

http
POST /hztech-interface/api HTTP/1.1
Host: main.example.com
Content-Type: application/json

{
  "appId": "SUB_APP_001",
  "version": "1.0",
  "timestamp": 1735516800000,
  "nonce": "d4e5f6a7-b8c9-0123-def0-123456789abc",
  "encryptKey": "MIIBOgIBAAJBAKj34GkxFhD90vcNLYLInFEX6...",
  "encryptData": "U2FsdGVkX1+jmZn5KqWYEgjPkQKpH5KqWYEg...",
  "sign": "MEUCIQDZ5KqWYEgjPkQKpH5KqWYEgjPkQKpH5KqWY..."
}

encryptData 解密后的业务数据

json
{
  "apiName": "查询用户列表",
  "apiCode": "user:list",
  "apiMethod": "GET",
  "apiPath": "/api/user/list",
  "requestParams": {
    "pageNum": {
      "type": "Integer",
      "required": true,
      "description": "页码",
      "example": 1
    },
    "pageSize": {
      "type": "Integer",
      "required": true,
      "description": "每页数量",
      "example": 20
    }
  },
  "responseParams": {
    "total": {
      "type": "Integer",
      "description": "总记录数"
    },
    "list": {
      "type": "Array",
      "description": "用户列表",
      "children": {
        "id": {
          "type": "String",
          "description": "用户ID"
        },
        "account": {
          "type": "String",
          "description": "账号"
        },
        "realName": {
          "type": "String",
          "description": "姓名"
        }
      }
    }
  },
  "description": "分页查询用户列表",
  "rateLimit": 1000,
  "status": 0
}

HTTP 响应示例

json
{
  "code": 200,
  "message": "success",
  "data": {
    "apiId": "API_001",
    "createTime": "2026-01-04T00:00:00"
  }
}

错误响应示例

json
{
  "code": 2302,
  "message": "接口编码已存在",
  "timestamp": 1735516801000
}

1.2 更新接口 ​

接口说明

更新已有接口的元数据信息。子应用向一单位一平台上报接口更新。

请求方式

POST

请求地址

POST /hztech-interface/api/update

交互方向

子应用 → 一单位一平台 (上报)

完整时序图

请求参数

参数名类型必填说明示例值
apiIdString是接口ID"API_001"
apiNameString否接口名称"查询用户列表(新版)"
apiPathString否接口地址"/api/user/list/v2"
requestParamsMap否接口参数说明见下方参数说明表
responseParamsMap否接口返回值说明见下方返回值说明表
descriptionString否接口描述"分页查询用户列表,支持更多筛选条件"
rateLimitInteger否速率限制(每秒请求数)2000
statusInteger否是否上架(1:已上架,0:未上架)1

requestParams 参数说明示例（更新后）

参数名类型必填说明示例值
pageNumInteger是页码1
pageSizeInteger是每页数量20
filtersObject否筛选条件-
└─ statusInteger否用户状态1

responseParams 返回值说明示例（更新后）

字段名类型说明
totalInteger总记录数
listArray用户列表
└─ idString用户ID
└─ accountString账号
└─ realNameString姓名
└─ statusInteger状态

HTTP 请求示例

http
POST /hztech-interface/api/update HTTP/1.1
Host: main.example.com
Content-Type: application/json

{
  "appId": "SUB_APP_001",
  "version": "1.0",
  "timestamp": 1735516800000,
  "nonce": "d4e5f6a7-b8c9-0123-def0-123456789abc",
  "encryptKey": "MIIBOgIBAAJBAKj34GkxFhD90vcNLYLInFEX6...",
  "encryptData": "U2FsdGVkX1+jmZn5KqWYEgjPkQKpH5KqWYEg...",
  "sign": "MEUCIQDZ5KqWYEgjPkQKpH5KqWYEgjPkQKpH5KqWY..."
}

encryptData 解密后的业务数据

json
{
  "apiId": "API_001",
  "apiName": "查询用户列表(新版)",
  "apiPath": "/api/user/list/v2",
  "requestParams": {
    "pageNum": {
      "type": "Integer",
      "required": true,
      "description": "页码",
      "example": 1
    },
    "pageSize": {
      "type": "Integer",
      "required": true,
      "description": "每页数量",
      "example": 20
    },
    "filters": {
      "type": "Object",
      "required": false,
      "description": "筛选条件",
      "children": {
        "status": {
          "type": "Integer",
          "description": "用户状态"
        }
      }
    }
  },
  "responseParams": {
    "total": {
      "type": "Integer",
      "description": "总记录数"
    },
    "list": {
      "type": "Array",
      "description": "用户列表",
      "children": {
        "id": {
          "type": "String",
          "description": "用户ID"
        },
        "account": {
          "type": "String",
          "description": "账号"
        },
        "realName": {
          "type": "String",
          "description": "姓名"
        },
        "status": {
          "type": "Integer",
          "description": "状态"
        }
      }
    }
  },
  "description": "分页查询用户列表,支持更多筛选条件",
  "rateLimit": 2000,
  "status": 1
}

HTTP 响应示例

json
{
  "code": 200,
  "message": "success",
  "data": {
    "apiId": "API_001",
    "updateTime": "2026-01-04T00:01:00"
  }
}

1.3 删除接口 ​

接口说明

删除指定的接口元数据。子应用向一单位一平台上报接口删除。

请求方式

POST

请求地址

POST /hztech-interface/api/delete

交互方向

子应用 → 一单位一平台 (上报)

完整时序图

请求参数

参数名类型必填说明示例值
apiIdString是接口ID"API_001"

HTTP 请求示例

http
POST /hztech-interface/api/delete HTTP/1.1
Host: main.example.com
Content-Type: application/json

{
  "appId": "SUB_APP_001",
  "version": "1.0",
  "timestamp": 1735516800000,
  "nonce": "d4e5f6a7-b8c9-0123-def0-123456789abc",
  "encryptKey": "MIIBOgIBAAJBAKj34GkxFhD90vcNLYLInFEX6...",
  "encryptData": "U2FsdGVkX1+jmZn5KqWYEgjPkQKpH5KqWYEg...",
  "sign": "MEUCIQDZ5KqWYEgjPkQKpH5KqWYEgjPkQKpH5KqWY..."
}

encryptData 解密后的业务数据

json
{
  "apiId": "API_001"
}

HTTP 响应示例

json
{
  "code": 200,
  "message": "success",
  "data": {
    "apiId": "API_001"
  }
}

1.4 查询接口详情 ​

接口说明

查询单个接口的详细信息。子应用向一单位一平台请求接口数据。

请求方式

POST

请求地址

POST /hztech-interface/api/detail

交互方向

子应用 → 一单位一平台 (查询)

完整时序图

请求参数

参数名类型必填说明示例值
apiIdString是接口ID"API_001"

HTTP 请求示例

http
POST /hztech-interface/api/detail HTTP/1.1
Host: main.example.com
Content-Type: application/json

{
  "appId": "SUB_APP_001",
  "version": "1.0",
  "timestamp": 1735516800000,
  "nonce": "d4e5f6a7-b8c9-0123-def0-123456789abc",
  "encryptKey": "MIIBOgIBAAJBAKj34GkxFhD90vcNLYLInFEX6...",
  "encryptData": "U2FsdGVkX1+jmZn5KqWYEgjPkQKpH5KqWYEg...",
  "sign": "MEUCIQDZ5KqWYEgjPkQKpH5KqWYEgjPkQKpH5KqWY..."
}

encryptData 解密后的业务数据

json
{
  "apiId": "API_001"
}

HTTP 响应示例

json
{
  "code": 200,
  "message": "success",
  "data": {
    "apiId": "API_001",
    "apiName": "查询用户列表",
    "apiCode": "user:list",
    "apiMethod": "GET",
    "apiPath": "/api/user/list",
    "requestParams": {
      "pageNum": {
        "type": "Integer",
        "required": true,
        "description": "页码",
        "example": 1
      },
      "pageSize": {
        "type": "Integer",
        "required": true,
        "description": "每页数量",
        "example": 20
      }
    },
    "responseParams": {
      "total": {
        "type": "Integer",
        "description": "总记录数"
      },
      "list": {
        "type": "Array",
        "description": "用户列表",
        "children": {
          "id": {
            "type": "String",
            "description": "用户ID"
          },
          "account": {
            "type": "String",
            "description": "账号"
          },
          "realName": {
            "type": "String",
            "description": "姓名"
          }
        }
      }
    },
    "description": "分页查询用户列表",
    "rateLimit": 1000,
    "status": 0,
    "createTime": "2026-01-04T00:00:00",
    "updateTime": "2026-01-04T00:00:00"
  }
}

1.5 接口列表查询 ​

接口说明

分页查询接口列表。子应用向一单位一平台请求接口列表数据。

请求方式

POST

请求地址

POST /hztech-interface/api/list

交互方向

子应用 → 一单位一平台 (查询)

完整时序图

请求参数

参数名类型必填说明示例值
pageNumInteger否页码(默认1)1
pageSizeInteger否每页数量(默认20)20
apiNameString否接口名称(模糊查询)"用户"
apiCodeString否接口编码(精确查询)"user:list"
apiMethodString否请求方法"GET"
statusInteger否状态(1:启用,0:禁用)1

HTTP 请求示例

http
POST /hztech-interface/api/list HTTP/1.1
Host: main.example.com
Content-Type: application/json

{
  "appId": "SUB_APP_001",
  "version": "1.0",
  "timestamp": 1735516800000,
  "nonce": "d4e5f6a7-b8c9-0123-def0-123456789abc",
  "encryptKey": "MIIBOgIBAAJBAKj34GkxFhD90vcNLYLInFEX6...",
  "encryptData": "U2FsdGVkX1+jmZn5KqWYEgjPkQKpH5KqWYEg...",
  "sign": "MEUCIQDZ5KqWYEgjPkQKpH5KqWYEgjPkQKpH5KqWY..."
}

encryptData 解密后的业务数据

json
{
  "pageNum": 1,
  "pageSize": 20,
  "apiMethod": "GET",
  "status": 1
}

HTTP 响应示例

json
{
  "code": 200,
  "message": "success",
  "data": {
    "total": 100,
    "pageNum": 1,
    "pageSize": 20,
    "pages": 5,
    "list": [
      {
        "apiId": "API_001",
        "apiName": "查询用户列表",
        "apiCode": "user:list",
        "apiMethod": "GET",
        "apiPath": "/api/user/list",
        "requestParams": {
          "pageNum": {
            "type": "Integer",
            "required": true,
            "description": "页码",
            "example": 1
          },
          "pageSize": {
            "type": "Integer",
            "required": true,
            "description": "每页数量",
            "example": 20
          }
        },
        "responseParams": {
          "total": {
            "type": "Integer",
            "description": "总记录数"
          },
          "list": {
            "type": "Array",
            "description": "用户列表",
            "children": {
              "id": {
                "type": "String",
                "description": "用户ID"
              },
              "account": {
                "type": "String",
                "description": "账号"
              },
              "realName": {
                "type": "String",
                "description": "姓名"
              }
            }
          }
        },
        "description": "分页查询用户列表",
        "rateLimit": 1000,
        "status": 0,
        "createTime": "2026-01-04T00:00:00",
        "updateTime": "2026-01-04T00:00:00"
      }
    ]
  }
}

数据模型 ​

接口对象 (ApiMetadata) ​

完整的接口元数据结构：

json
{
  "id": "string",             // 接口ID(系统生成)
  "apiName": "string",           // 接口名称
  "apiCode": "string",           // 接口编码(唯一)
  "apiMethod": "string",         // 请求方法
  "apiPath": "string",           // 接口路径
  "requestParams": "Map<String, Object>",  // 接口参数说明
  "requestBody": "Map<String, Object>",  // 接口参数说明
  "responseParams": "Map<String, Object>", // 接口返回值说明
  "description": "string",       // 接口描述
  "rateLimit": 1000,             // 速率限制
  "status": 0,                   // 是否上架: 1-已上架, 0-未上架
  "createTime": "2026-01-04T00:00:00",  // 创建时间
  "updateTime": "2026-01-04T00:00:00"   // 更新时间
}

字段说明 ​

字段类型必填说明约束
idString是接口唯一标识系统生成，不可修改
apiNameString是接口名称2-100个字符
apiCodeString是接口编码(唯一)英文小写+冒号，全局唯一
apiMethodString是接口请求方法GET/POST/PUT/DELETE 等
apiPathString是接口地址(路径)以/开头
requestParamsMap否接口参数说明存储参数名、类型、是否必填、说明等
requestBodyMap否接口参数说明存储参数名、类型、是否必填、说明等
responseParamsMap否接口返回值说明存储返回字段名、类型、说明等
descriptionString否接口描述最多500个字符
rateLimitInteger否速率限制(每秒请求数)大于0
statusInteger是是否上架1-已上架, 0-未上架
createTimeString是创建时间ISO 8601格式
updateTimeString是更新时间ISO 8601格式

枚举值说明 ​

请求方法 (apiMethod)：

  • GET: 查询请求
  • POST: 创建请求
  • PUT: 更新请求
  • DELETE: 删除请求
  • PATCH: 部分更新请求

接口状态 (status)：

  • 1: 已上架
  • 0: 未上架

错误码 ​

业务错误码 ​

错误码说明处理建议
2301接口不存在检查apiId是否正确
2302接口编码已存在使用其他编码
2303接口名称已存在使用其他名称
2304接口路径格式错误检查apiPath是否以/开头
2305接口方法不支持检查apiMethod参数
2306速率限制值无效检查rateLimit参数(必须大于0)

系统错误码 ​

错误码说明处理建议
1001时间戳过期同步系统时间
1002重复请求检查nonce生成逻辑
1003签名验证失败检查密钥配置
1004解密失败检查密钥配置
1005appId不存在检查appId注册
1006业务逻辑错误根据具体错误处理

相关文档 ​

文档版本: v1.0.0 最后更新: 2026-01-04

最近更新