# RESTful API standard

**Repository Path**: chen-binfa/restful-api-standard

## Basic Information

- **Project Name**: RESTful API standard
- **Description**: 本项目是介绍一种基于RESTful架构定义出来的一个自己或团队内部使用的标准化方案。
根据使用习惯对API使用的请求方式，参数，格式，类型等进行明确定义，从而规范开发流程。
- **Primary Language**: NodeJS
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2022-04-22
- **Last Updated**: 2022-11-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RESTful API standard

### 说明
本项目是介绍一种基于RESTful架构定义出来的一个自己或团队内部使用的标准化方案。
根据使用习惯对API使用的请求方式，参数，格式，类型等进行明确定义，从而规范开发流程。

### 哲学
RESTful架构，就是目前最流行的一种互联网软件架构。它结构清晰、符合标准、易于理解、扩展方便，所以正得到越来越多网站的采用，但此规范的定义颇为宽泛，由于每个人对它理解不同，就会定义出不同的标准，如：更新资源的method，有些人使用PUT ，有些人喜欢用PATCH，对于response状态码字段名称，有些人用code，有些人则喜欢用status，这些虽然符合RESTful原则的，但如果在团队中，不同的后端开发人员或不同的项目使用不同的定义，前后端就都无法做到代码复用，开发人员在不同项目中切换，就非常容易出bug。
所以，一份更明确，更详尽的内部API标准就显得尤为重要，前后端统一执行，能减少非常多的沟通成本，提高协作效率。

### 说明

1.  定义内部标准的首要原则是要符合RESTful规范，对RESTful规范中，有多种方案的部分要确定下来使用的一种
2.  每一个细节定义要尽量详细，减少开发人员的纠结时间，特别是有选择困难症的同学
3.  通用原则，要考虑到未来的业务场景需求，尽量保持兼容性，可拓展性


### 主要定义以下几方面

| name               | about             |
| ------------------ | ----------------- |
| URL                | 路径              |
| Method             | 请求方法          |
| Authorization      | 授权/登录验证方式  |
| Request Data Type  | 请求参数格式      |
| Response Data Type | 返回数据格式      |


### URL

1.  版本号不要添加到URL中，如:/api/v1.0/user 而是添加到请求头上，使用version字段
2.  基于面向资源，API接口url设置上使用名词来设置，可以写复数形式,例如：设置/api/source，注意：source为名词，如果设置成get-source则是动词形式
3.  get请求的资源，使用query形式，如：/api/source?id=2,不要使用param路径的形式，如：/api/source/2
4.  open api的url以public开头，如 /public/article/list



### HTTP Method

| Method Name | About                                                                |
| ----------- | -------------------------------------------------------------------- |
| GET         | 从服务器上获取一项或多项资源                                         |
| POST        | 从服务器查询 List                                                    |


### Authorization

1.  为了适应更多的端和更广泛的应用场景，放弃session,统一使用jwt [JWT定义的规范](https://jwt.io/introduction/) 。
2.  jwt的token放到http请求头中，字段名：Authorization,Bearer格式,token获取后存储到localStorage中 ，因为cookie是无法跨域，部分浏览器需要用户授权，并且有时长度不足，使用上有很多不方便。
3.  使用方式：

``` javascript
    Authorization:Basic空格token字符串
```


### Request Data type

1.  PUT Method新增或更新，不带id列表示新增，否则为更新，id列是个数组，如：[1,2],表示同时更新id=1和id=2的行。
2.  DELETE Method 删除一条或多条记录，id列是需要删除的行的id组成的数组
3.  POST Method 查询列表，
列表api是最常用也是功能最多的接口，这个接口的设计上，要同时实现分页，筛选，排序等功能，如果让后端根据不同业务需求来定义，在接口数量不多的情况下，没什么问题，接口数量多了后就会越来越混乱，每个接口都要写一个处理函数或类来处理，使用typescript时也要定义很多更多的类型，代码复用率低，如：
> - 用户列表 /api/user ,post参数：{count:3,age:20}  
> - 产品列表 /api/product ,post参数：{minPrice:3,maxPrice:20}


这样看起来更简单明了，但当增加需求时，如排序或过滤条件，就只能不断的拼接更多的参数进去，而且每个参数在前后端都要写对应的核验方法和处理逻辑，使用起来很让人头疼，无法实现程序员该懒就懒的原则。

所以，有没有一种简单标准，能够预判甲方的可能需求，运筹帷幄呢，请往下看。
定义如下：(所有字段都是可选)
```javascript
{
    pageindex:number,//当前页码，默认：1
    pagesize:number,//每页记录数，默认：20    
    field:[string,....],//需要返回的字段，使用场景：有些表字段太多，如果全部返回，无故增加了开销，无默认值
    filterType:string,//过滤结合类型，固定值 and 或者 or，默认值:and
    filter:[ //过滤器数组，可以多个，过滤器之前的关系看filterType参数，无默认值
        {
            column:string,//过滤字段，如：id
            sign:string,//过滤类型，可选值 ：=,!=,<,>,<=,>=,between,betweenTime,like,notlike,in,notin
            values:array //值，数组，如要查询id=1,2,3的记录，这里填[1,2,3]
        },
        ...
    ],
    sorter:[//排序器数组,多个排序器越靠前权重越高，默认值 id desc
        {
            column:string,//排序字段
            type:string//排序类型，升序：asc,降序：desc
        },
        ....
    ],
    groupby: "",//group by 字段 , 无默认值
    onlytotal: false,//是否仅显示数量，默认是false
}
```

### Response Data type


- 返回统一为Json格式，定义如下：

```javascript
{
    code:1,//1:成功,
    msg:'ok',// ok：成功,noauth表示无权限
    data:<Object>
}
```
- 在列表API中，返回的data中增加一个表头字段，如：

```javascript
{
    code: 1,//1:成功
    msg: string // ok:成功
    data: {
        header: [ //表头
            {
                title: string,//列名称
                dataIndex: string,//列字段名，对应List中行的key
                width: string //列宽度,如：'100px'或'20%'
            },
            ...
        ],
        list: [
            {
                id: number,
                ... 更多列
            },
            ...
        ],
        total: number //总数量
    }    
}
```