当前位置：首页 > news >正文

服务端 http接口文档标准参考

news 2025/11/13 12:25:32

接口描述

超文本传输协议（Hypertext Transfer Protocol，HTTP）是一个简单的请求-响应协议，它通常运行在TCP之上。它指定了客户端可能发送给服务器什么样的消息以及得到什么样的响应。请求和响应消息的头以ASCII形式给出；而消息内容则具有一个类似MIME的格式。超文本传输协议是一种用于分布式、协作式和超媒体信息系统的应用层协议，是万维网WWW（World Wide Web）的数据通信的基础

交互过程

系统数据交互主体分为接口请求方和接口响应方，接口请求方和接口响应方使用HTTP协议进行数据传输，实现各个接口功能。其中接口请求方为客户端，主动向接口响应方发起HTTP连接请求；接口响应方为服务端，创建HTTP服务端口，侦听处理接口请求方的请求。

典型的HTTP事务处理有如下的过程：

（1）客户与服务器建立连接；

（2）客户向服务器提出请求；

（3）服务器接受请求，并根据请求返回相应的文件作为应答；

（4）客户与服务器关闭连接。

http接口报文格式

HTTP报文由从客户机到服务器的请求和从服务器到客户机的响应构成。请求报文格式如下：

请求行－通用信息头－请求头－实体头－报文主体

应答报文格式如下：

状态行－通用信息头－响应头－实体头－报文主体

双方系统必备功能

日志功能

所有的系统之间接口调用,双方必须登记详细的日志,含如下内容[接口地址,入参内容,返回内容,调用时间,错误原因], 对于操作级别很高的接口，日志级别要标注为最高。

系统最好提供日志查询功能可按操作日期查询。

接口全局公用约定

超时时间设置

连接超时

（Connection Timeout）：

这是指客户端尝试与服务器建立连接时的最大等待时间。如果在这个时间内没有建立连接（例如，服务器没有响应或者网络延迟很高），客户端就会放弃尝试并抛出一个超时异常。

连接超时全局设置为2秒，为了系统稳定,超过2秒，日志平台需要报警显示网络波动问题。

读超时

（Read Timeout）：

读超时是指客户端与服务器连接成功后，等待服务器发送数据的最大时间。如果在这个时间内客户端没有收到任何数据，就会认为读取操作超时并抛出异常。这通常发生在服务器处理请求的时间过长，或者网络传输延迟导致数据包迟迟未到达客户端。

读超时全局设置为20秒，对于超过30秒的接口，服务端应补充另外一个数据回示接口，双方约定查询接口的时间

写超时

（Write Timeout）：

写超时是指在客户端尝试向服务器发送数据时的最大等待时间。如果客户端在这段时间内未能完成数据的发送，就会认为写操作超时。这可能是因为网络速度慢或者服务器处理写入请求的速度慢。

写超时全局设置为20秒，客户端如果数据太多，双方约定分批提交数据。

服务端接口认证方式

服务端可提供多种认证方式

1.基于token的认证方式
优点：
隐藏了用户的真实信息，安全性较高。
实现与使用都较为简单，易于开发。
缺点：
token会在一定时间内过期，需要重新生成，增加了操作流程。
token被盗后，攻击者可以随意操作，因此需要对token进行有效的安全存储和传输。

2.基于身份验证协议的认证（如OAuth 2.0）
优点：
隐藏了用户的真实信息，安全性较高。
缺点：
需要搭建一个授权服务，开发难度较大。

3.基于HTTP基本认证
优点：
易于开发
缺点：
将用户名和密码封装在请求的Header中不安全，并且容易泄露用户名和密码

4.基于IP白名单的认证方式
优点：
简单直接，易于实现和使用。
缺点：
受到IP地址变动的影响较大，需要不断地更新允许访问的ip列表。
安全性较低，容易受到攻击者的伪造ip请求所攻击。

5.基于数字签名的认证方式
优点：
安全性较高，可以有效防止中间人攻击。
不需要像token一样限定时间，签名一经生成，即可以一直使用。
缺点：
实现起来较为复杂，需要使用公私钥加密的机制。
难度大，易于出现提高风险。

6.基于固定的AppKey和AppSecrity
优点：
开发简单，可以集中对发放的对象进行控制
缺点：
安全性不高，一旦AppKey和AppSecrity泄露就会导致

具体的接口认证约定

服务端返回数据格式

json范例:

成功{"success":true,"value":[{"stationLatitude":36,"stationLongitude":119,"stationAreaCode":"350206","stationName":"站点1","stationId":"1635953780895797249"}]}

失败

{"success":false,"message":"对接授权不对"}

字段	字段说明	字段类型	字段备注
success	请求是否成功	布尔类型	true 成功 false失败
value	返回值	对象
message	消息	字符串	接口失败异常信息

接口相关数据字典

x字典

字典值	值描述

接口清单

功能1

接口描述

功能描述：
请求地址:
请求方式:
入参格式:

接口入参

字段	字段说明	字段类型	字段备注
operId	操作流水号	字符串	见3.2
operType	操作类型	字符串	见3.2
stationIds	选中的站点	数组	选中的站点id