JavaScript - 后端接口编写规范示例（API）

布满荆棘的人生 2023-03-06 03:58 15阅读 0赞

## 前言 ##

当后端完成一个 `API` 接口时，通常需要 **与前端人员沟通接口的细节**，这时候，一个文档就能节省很多效率，大大减少沟通成本，如何撰写一份规范文档呢？

## 功能描述 ##

> 用最简洁清晰的语言，让不懂后端的前端一看就懂。

主要说明该方法实现什么功能（很重要），涉及术语需要标注。

## URL地址 ##

例如：/admin/user/

## 请求方式 ##

调用该接口前端需要使用什么方式来请求（GET / POST / PUT / DELETE …）

## 请求参数 ##

> 此块最好使用表格来描述。

调用该接口时，前端需要传递哪些参数值，主要有以下几个方面：

*  【字段】：对应的字段名称，如 `userName` / `pwd`。
 *  【说明】：对于该字段的说明，如 `用户名` / `密码`。
 *  【类型】：对于该字段类型，如 `Array` / `Object` 。
 *  【是否必填】：`Y/N` / `True/False`
 *  【备注】：对于该接口有什么备注。

## 返回结果 ##

请求该接口方法预期返回什么样的结果。

## 请求示例 ##

对该方法做一个请求示例，来进一步减少前端思考成本。

wx.request({ 
      url: 'test.php', //接口地址
      data: { 
        x: '',
        y: ''
      },
      header: { 
        'content-type': 'application/json' // 默认值
      },
      success (res) { 
        console.log(res.data)
      }
    })

## 返回示例 ##

对该方法做一个返回示例，来进一步减少前端思考成本。

{ 
      code:100,
      message: '请求示例',
      data: { 
    	..
      }
    }

## 状态码说明 ##

> 后端 **自定义状态码** 必须要写此状态码说明。

对返回的状态码说明，如返回 `400` 代表错误，`200` 代表正常。

--------------------

**到这里就结束了，当然要遵守公司需求以及公司制定的规范。**

--------------------

## DEMO（简易示例） ##

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDE5ODk2NQ_size_16_color_FFFFFF_t_70]

## 写在后面 ##

目前市面上有很多网站提供 **团队文档协作** 服务，可以使用它们解决方案，团队可以在线撰写文档，可被团队所有人可见。大大减少沟通成本，这里不列出了，避免广告嫌疑。

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDE5ODk2NQ_size_16_color_FFFFFF_t_70]: /images/20230208/a7007083ffcc42128f78be3215ac68b5.png