什么是接口文档,如何写接口,有什么规范?

含义是：在项目开发中，web项目的前后端分离开发，APP开发，需要由前后端工程师共同定义接口，编写接口文档，之后大家都根据这个接口文档进行开发，到项目结束前都要一直维护。

目的是：项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发。项目维护中或者项目人员更迭，方便后期人员查看、维护。

规范是：以/a开头，如果需要登录才能调用的接口(如新增、修改；前台的用户个人信息，资金信息等)后面需要加/u，即：/a/u；中间一般放表名或者能表达这个接口的单词；get方法，如果是后台通过搜索查询列表，那么以/search结尾，如果是前台的查询列表，以/list结尾；url参数就不说了。

API（Application Programming Interface，应用程序接口）是一些预先定义的接口（如函数、HTTP接口），或指软件系统不同组成部分衔接的约定。用来提供应用程序与开发人员基于某软件或硬件得以访问的一组例程，而又无需访问源码，或理解内部工作机制的细节。

应用程序接口又称为应用编程接口，是一组定义、程序及协议的集合，通过 API接口实现计算机软件之间的相互通信。API 的一个主要功能是提供通用功能集。

API同时也是一种中间件，为各种不同平台提供数据共享。程序设计的实践中，编程接口的设计首先要使软件系统的职责得到合理划分。良好的接口设计可以降低系统各部分的相互依赖，提高组成单元的内聚性，降低组成单元间的耦合程度，从而提高系统的可维护性和可扩展性。

3.3.6.1 海洋标量场数据绑定接口规范

海洋标量场数据绑定接口是为了向海洋标量场时空过程可视化功能提供数据的辅助程序接口，包括点过程可视化服务接口、线过程可视化服务接口和面过程可视化服务接口。下面是三个接口的定义规范。

(1)点过程可视化接口规范

public bool Identify(string sServerName，string sServerType，double dX，double dY，Ar-rayList iLayerIDArrayList，out ArrayList

sLayerNameArrayList，out ArrayList sValueArrayList)

sServerName: 服务名，string 类型。

sServerType: 服务类型，string 类型。

dX: 选择位置 X 坐标，double 类型。

dY: 选择位置 Y 坐标，double 类型。

iLayerIDArrayList: 图层 ID 起始位置，ArrayList 类型。

sLayerNameArrayList: 返回的图层名列表，ArrayList 类型。

sValueArrayList: 返回的图层的数据，ArrayList 类型。

(2)线过程可视化服务接口规范

Public bool GetProfiles(string sServerName，string sServerType，ArrayList

dXArrayList，ArrayList dYArrayList，ArrayList iLayerIDArrayList，out ArrayList sLayer-NameArrayList，out ArrayList sValueStringArrayList)

sServerName: 服务名，string 类型

sServerType: 服务类型，string 类型。

dXArrayList: X 坐标数组，数组列表类型。

dYArrayList: Y 坐标数组，数组列表类型。

ILayerIDArrayList: 层 ID 数组列表，数组列表类型。

sLayerNameArrayList: 返回参数，层名数组列表，数组列表类型。

sValueStringArrayList: 返回参数，值数组列表，数组列表类型。

(3)面过程可视化服务接口规范

public string GetImageURL(string ServiceURL，double ［］ arrl，int FromId，int ToId，out string str)

ServiceURL: 服务的地址，string 类型。

arrl: 选择范围坐标，double 数组。

FromId: 图层起始 ID，int 类型。

ToId: 图层终止 ID，int 类型。

Str: 输出参数，返回 URL 地址，string 类型。

3.3.6.2 ARGO 信息服务绑定接口规范

为了进行 ARGO 数据的获取和图形表达，需要开发数据获取、曲线生成的函数接口，其接口规范如下:

(1)ARGO 数据获取接口规范

Public DataSet GetArgoNumbCycleDataSet()

本接口无参数，返回制定 ARGO 数据内容。

(2)通过属性生成 Argo 数据曲线图接口规范

Public String CreatGraphByAttribute(float x，float y，string graphType)

X∶X 坐标值，float 类型。

Y∶Y 坐标值，float 类型。

graphType: 图标类型，string 类型。

(3)通过空间位置生成 Argo 数据曲线图接口规范

Public ArrayList CreatGraphByCoordinate(String plateformNumb， string circleNumb，string graphType)

plateformNumb: 平台编号，String 类型。

circleNumb: 圆半径，string 类型。

graphType: 图标类型。

3.3.6.3 海洋矢量场数据服务绑定规范

矢量场数据包括风场数据和流场数据，接口函数包括获得矢量场数据列表、获得矢量场数据内容、生成矢量场图形、获得点选处矢量场属性和序列化显示。下面分别介绍其接口规范。

(1)获得流场数据文件列表接口规范

Public ArrayList Get_CurrentsList()

本接口无参数，返回所有流场数据文件列表。

(2)获得海流文件中数据内容

Public ArrayList Get_CurrentsData(string fileName)

fileName: 流场数据文件名，string 类型。

本接口函数返回文件中的数据值。

(3)生成流场要素接口规范

Public String DrawCurrents(object ［］fileDataList )

fileDataList: 流场文件数据值。

本接口函数生成流场矢量图。

(4)获得点选处海流数据属性接口规范

Public ArrayList Get_Property(float x，float y )

X: 鼠标点选处 X 坐标，float 类型。

Y: 鼠标点选处 Y 坐标，float 类型。

本接口函数的返回值为点击处的属性值。

(5)序列化显示接口规范

Public ArrayList SeriesShow(String ［］fileName )

fileName: 流场数据文件名，string 类型。

本接口规范返回剖面文件序列。

(6)获得风场数据文件列表接口规范

Public ArrayList Get_WindsList()

本接口无参数，返回所有风场数据文件列表。

(7)获得风流文件中数据内容

Public ArrayList Get_WindsData(string fileName)

fileName: 风场数据文件名，string 类型。

本接口函数返回文件中的数据值。

(8)生成风场要素接口规范

Public String DrawWinds(object ［］fileDataList )

fileDataList: 风场文件数据值。

本接口函数生成风场矢量图。

(9)获得点选处风场数据属性接口规范

Public ArrayList Get_Property(float x，float y)

X: 鼠标点选处 X 坐标，float 类型。

Y: 鼠标点选处 Y 坐标，float 类型。

本接口函数的返回值为点击处的属性值。

(10)获得风场玫瑰图

Public String Get_RoseGraph(String time float MaxX，float MaxY float MinX，float MinY)

Time: 数据时间，string 类型。

MaxX: 最大 X 坐标值，float 类型。

MaxY: 最大 Y 坐标值，float 类型。

MinX: 最大 X 坐标值，float 类型。

MinY: 最大 Y 坐标值，float 类型。

返回风玫瑰图的 URL。

(11)序列化显示接口规范

Public ArrayList SeriesShow(String ［］fileName )

fileName: 流场数据文件名，string 类型。

本接口规范返回剖面文件序列。

由于接口规范的定义和接口的实际实现是分开的两个部分, 而且涉及到多人协作, 因此在开发过程中可能出现接口规范与实现不同步, 最终造成实际的接口不符合规范的定义, 接口规范就会慢慢失去存在的意义.

为了尽量避免这种问题, 后端在实现接口的过程中应该确保与接口规范保持一致, 一旦出现分歧, 必须同步修改接口规范, 尽可能保持沟通.

专门的api应用使用独立域名 https://api.example.com

简单的可使用api前缀区分 https://www.example.com/api

接口版本的控制，可以在程序发布时，不同版本的业务逻辑在一定程度上避免受到影响。

https://api.example.com/v {n}

应该将API的版本号放入URL。

采用多版本并存，增量发布的方式。

n代表版本号，分为整型和浮点型

整型： 大功能版本， 如v1、v2、v3 ...

浮点型： 补充功能版本， 如v1.1、v1.2、v2.1、v2.2 ...

客户端任何的修改都是需要发版的，发版需要审核流程。

客户端尽量只负责展示逻辑，不处理业务逻辑

客户端不处理金额的计算

客户端少处理请求参数的校验与约束提示

图片文案等，与校验规则类似，通过接口返回，并提供默认。

​ url连接一般采用https协议进行数据传输，可以提高数据交互过程中的安全性。

区分版本

合并接口

字段简写

无用字段清理

图片裁剪

局部刷新

预加载

其他

接口安全，防参数篡改

频率的控制

数据存储

是否需要依赖于第三方

服务降级，熔断和限流

拆分

扩展性

适配性

幂等

重复提交

部署

缓存穿透、缓存雪崩和缓存击穿

是否需要白名单

预加载

重试

异步

服务端推送或者客户端拉取数据

隔离（例如内网的中台服务，后端服务）

健康检查，后台大盘监控可视化，故障主动通知

---