华东师范大学开发者平台

主题

架构设计 ​

API 网关 ​

每一个提供数据的业务系统都可以视为数据的"生产者"，每一个需求数据的业务系统也可以视为数据的"消费者"。连接"消费者"与"生产者"之间的即为API网关。API网关将统一对外提供接口的认证，授权，限流，熔断等通用功能，并以代理的方式转发经过API网关授权的请求。典型的 API 网关架构如图所示：

数据中心平台将基于集成的数据提供各类基础数据接口，是整个架构体系下最大的数据“生产者”。于此同时，我们也欢迎其他各类业务与数据中心平台进行接口集成，提供各类更贴近业务，尤其是提供互操作性的集成接口，进一步丰富平台的开放生态。

后端接口集成规范 ​

后端接口授权 ​

鉴于我们基于 API 网关统一进行认证，授权，限量等策略，因此后端只需要针对 API 网关本身鉴权即可。我们建议后端接口侧在和 API 网关对接时，统一使用一下的鉴权方式：

  • HTTP Header 嵌入的静态令牌（必须）

    后端应该通过与 API 网关约定的字段，从 HTTP Header 中获取静态令牌，以此来鉴权。例如我们约定的字段为 X-API-KEY，则后端应该从 HTTP Header 中获取 X-API-KEY 字段的值，然后与后端设定分配给 API 网关的令牌进行比对，以此来鉴权。

  • IP 地址白名单(可选)

    如果需要，后端应该添加 API 网关的 IP 地址作为白名单，仅允许白名单内的 IP 访问后端接口，以增加接口授权的安全性。

数据响应结构 ​

鉴于我们基于 API 网关统一进行认证，授权，限量等策略，实际业务接口则以代理方式请求业务后端API。因此返回的数据响应结构取决于后端服务返回的响应结构体。我们建议后端接口侧统一使用一下的响应结构风格

参数名类型备注
dataobject根据业务需求自定义,建议以数组形式返回。空数组表示未命中查询。以小驼峰规则命名字段
errCodenumber错误代码，0标识请求正确，其他由业务自行定义
requestIdstring建议返回requestId，与日志相匹配，供debug核查
errMsgstring错误的详细信息，success表示正确
json
{
	"data": [{
		"userType": "教职工",
		"departmentId": "0445",
		"department": "信息化治理办公室",
		"userId": "20*****73",
		"name": "****"
	}],
	"errCode": 0,
	"requestId": "6a0f0e4b16224492292693845e2c35",
	"errMsg": "success",
}

错误响应结构 ​

鉴于我们基于 API 网关统一进行认证，授权，限量等策略，实际业务接口则以代理方式请求业务后端API。为了区分 API 网关侧的错误响应与后端的错误响应，所有在API网关侧产生的错误，错误信息不会返回在 http body 中，将 http header 的方式插入以下错误字段。

  • X-Ca-Request-Id。请求唯一ID，请求一旦进入API网关应用后，API网关就会生成请求ID并通过响应头返回给客户端，建议客户端与后端服务都记录此请求ID，可用于问题排查与跟踪

  • X-Ca-Error-Message。API网关返回的错误消息，当请求出现错误时API网关会通过响应头将错误消息返回给客户端

  • X-Ca-Error-Code。API网关系统错误码，当请求出现错误被网关拦截后，由API网关提供的错误码:

例如我们使用一个错误的 token 来请求接口，则会得到以下返回

Server: nginx
Date: Mon, 31 May 2021 08:31:42 GMT
Content-Length: 0
Connection: keep-alive
X-Ca-Error-Code: A401OT
X-Ca-Error-Message: Invalid Token: token is not valid
X-Ca-Request-Id: C7B6C8C5-5576-49E9-ABAA-AD6E0F6F6749

协议和接口 ​

开放平台遵顼 OAuth2 标准协议，并基于此模式授权并提供 RESTFUL 风格的接口。

除本文档公开的接口列表，和授权协议之外，我们也支持其他协议的接入和接口的定制。如有此类定制需求，请单独联系我们。