点击上方蓝字一起上车吧～

1

01

定义

1、基础接口：单一职责原则，每个接口只负责各自的业务，下接db，通用性强。

2、聚合接口：根据调用方需求聚合基础接口数据，业务性强。

1

02

协议

1. 客户端在通过 API 与后端服务通信的过程中， 应该使用 HTTPS(生产环境) 协议

2. 服务端响应的数据格式统一为JSON

1

03

域名host

prd环境：https://xxx-xxx-api.example.com/

uat环境：https://xxx-xxx-api-uat.example.com/

test环境：https://xxx-xxx-api-test.example.com/

dev环境：https://xxx-xxx-api-dev.example.com/

将api放到子域名里，这种做法可以保持某些规模化上的灵活性。

1

04

路径path

path命名应该是以资源为导向的命名，对资源的操作是由HttpMethod(get、post、put、delete)来决定。所以一般来说url上的单词都应该是名词，一定不要是动词。一般遵循以下约定：

(1)URL 的命名必须全部小写；

(2) URL 必须 是易读的 URL；

(3)一定不可 暴露服务器架构

(4)出现复合词汇使用下划线分隔，例如：animal_types

举几个正面例子：

新增用户：http://localhost/user post方法提交;

修改用户：http://localhost/users put方法提交;

删除文章：http://localhost/articles?author=1&category=2 delete方法提交;

查询用户：http://localhost/users get方法提交;

查询文章：http://localhost/articles?author=1&category=2get方法提交;

错误的例子如下：

http://localhost/get_user

https://api.example.com/getUserInfo?userid=1

https://api.example.com/getusers

https://api.example.com/sv/u

https://api.example.com/cgi-bin/users/get_user.php?userid=1

1

05

动词

RESTful 的核心思想就是，客户端发出的数据操作指令都是"动词 + 宾语"的结构，动词通常就是四种 HTTP 方法，对应 CRUD 操作：

其中

(1)删除资源 必须 用 DELETE 方法

(2)创建新的资源 必须 使用 POST 方法

(3)更新资源 应该 使用 PUT 方法

(4)获取资源信息 必须 使用 GET 方法

针对每一个路径来说，下面列出所有可行的 HTTP 动词和端点的组合

1

06

入参

1、如果记录数量很多，服务器不可能都将它们返回给用户。API 应该 提供参数，过滤返回结果。下面是一些常见的参数。

?limit=10：指定返回记录的数量

?offset=10：指定返回记录的开始位置。

?page=2&per_page=100：指定第几页，以及每页的记录数。

?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。

?animal_type_id=1：指定筛选条件

所有URL参数 必须是全小写，必须使用下划线类型的参数形式。

分页参数 必须 固定为 page 、 per_page

经常使用的、复杂的查询 应该 标签化，降低维护成本，如

GET /trades?status=closed&sort=sortby=name&order=asc

#   可为其定制快捷方式

GET /trades/recently_closed

2、入参可分为业务参数和公共参数；公共参数有：

1

07

响应

1、出参(返回值)：必须的字段有：

2、如果请求处理完全正确，则状态码为0 ；

3、状态码暂定8位数数字，前4位为某一个应用(服务)拟的一个数字，后4位为具体的状态值。状态码分为2种---公共和自定义，公共码以0打头+3位数。

比如：

99990400  --客户端错误，比如请求语法格式错误、无效的请求、无效的签名等。

99991001  -----用户Id不能为空

响应的公共码如下：

1

08

项目结构

1、采用经典DDD领域取到模型：(默认一个解决方案有5个项目)

5个项目分别为：

Web层为最外层接口定义；

Service为具体的应用服务处理；

Infrastructure基础设施层，处理具体的业务逻辑和数据DB的处理；

Domain领域层为模型和仓库接口interface;

Common为通用的一些Helper类；

2、一个解决方案创建5个项目(如上图)，并且里包含常用的基础组件：Log4net日志，听云监听；dockerfile,skywalking,全局异常捕捉，接口请求开始和结束的日志记录，swagger，service层的依赖注入，Mapping等。

3、代码全部采用依赖注入写法，尽量少些静态类；

4、HttpClient的写法：使用采用.netcore官方提供的方法，采用工厂类+依赖注入方式：实例代码如下：

1

09

日志

1、接口开始前和结束后都已在LogstashFilter里记录，接口里就不需要再次记录；

LogstashFilter里的代码如下：

2、try Catch日志必须要添加LogError日志，并且要将堆栈信息记录，代码如下：

▼推荐阅读▼