编码规范

2023-02-19 09:32 作者:小刘Java之路 0人读过 | 我要投稿

RESTful API

RESTful 是⼀种架构设计⻛格。核⼼思想是⼀切皆资源。RESTful架构中，将所有的东⻄都视为资源，每个资源对应了⼀个URI（统⼀资源标识符）所有的操作都是对资源的增删改查，这些操作对应了 HTTP 的 GET、POST、PUT、DELETE。

Endponits（端点）

端口是特定资源集合URL。在端点的设计中，你必须遵循下列约定：

URL 的命名必须 全部小写，多个单词使用中横线-连接，而不是使用下划线-

浏览器中超链接显示的默认效果是，⽂字并附带下划线，如果API以 _ 隔断单词，⼆者会重叠，影响可读性。

URL中的资料（resource）的命名必须是名词，并且必须是复数形式
必须优先使用RESTful类型的URL
URL必须是易读的。

在实际的项目开发中，为了保证URL的全局统一，这里规定URL必须添加系统名，并且所有的URL必须使用

/api作为前缀。

如下所示：👇

/api/<系统名>/< 资源名 >/<⼦资源名>

注意：

1.URL通常区别大小写（机器名称除外）参考W3C URL规范

2.Tomcat中URL就是区分大小写，URL参数同样区分大小写。且URL格式验证非常格式。

举例：

http://api.highzap.com/api/users 能正常访问。⽽地址：http://api.highzap.com//api/users （仅仅是多了⼀个 “/”）访问时会响应404 找不到此路径。同样的情况在 .NET写的⽹站中却能正常访问，且URL与参数都不区分⼤⼩写。

HTTP 动词

客户端对于资源的具体操作类型（增删改查），由 HTTP 动词表示。常⽤的 HTTP 动词有下⾯五个

GET （get） :从服务器取出资源（⼀项或多项）。
POST (post) :在服务器新建⼀个资源。
PUT (put) : 在服务器更新资源（客户端提供改变后的完整资源）。
PATCH (patch): 在服务器更新资源（客户端提供改变的属性）。
DELETE (delete) : 从服务器删除资源。

其中

1.删除资源必须使⽤ DELETE ⽅法

2.创建资源必须使⽤ POST ⽅法

3.更新资源应该使⽤ PUT ⽅法

4.获取资源信息必须使⽤ GET ⽅法

针对每⼀个端点来说，下⾯列出所有可⾏的 HTTP 动词和端点的组合

Java实现代码参考 ➡

https://www.yuque.com/docs/share/f28a24ea-32f8-4f03-8e1f-80e1dd84b27f?# 《Maven私服配置》

问题：

能不能在我以前的maven的settings的配置中配置私服

Version （版本管理）

在URL中嵌入版本编号

这种做法是版本号直观、易于调试，缓存友好。
1.这种做法是版本号直观、易于调试，缓存友好。

Filter (资源过滤)

对于资源集合来说，可以通过URL参数对其进⾏过滤。

常见的过滤参数

👇常见的过滤参数：

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

?page=2&size=100：指定第⼏⻚，以及每⻚的记录数。

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

?station_type_id=1：指定筛选条件

URL参数命名规范

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

注意：是URL参数采取全⼩写的形式，多个单词间使⽤ "_" 分隔。

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

1 列出未关闭的按照名称升序排列的交易信息

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

3 # 可为其定制快捷⽅式

4 GET /trades/recently_closed

pagination (分页)

分⻚就是⼀种最典型的资源过滤，分⻚参数必须固定为 page 、 size 、其他参数。

JWT （Json Web Token）是⾏业普遍采⽤的⼀种认证协议

客户端在获得 access_token 的同时在响应中还包含⼀个名为 expires_in 的数据，它表示当前 token 会在多少秒后失效， refresh_token 刷新令牌⽤于在 token 到期后重新获取 token ，⼀般 refresh_token 的过期时间为⼀个⽉，⽽ token 的过期时间则⽐较短。

{
2 "access_token": "token ...",
3 "refresh_token": "refresh_token ...",
4 "token_type": "Bearer",
5 "expires_in": 3600
6 }

客户端请求时携带Token

客户端在请求需要认证的 API 时，必须在请求头 Authorization 中带上 access_token 。

Authorization: Bearer <Token>

令牌过期/⽆效

当使⽤过期/或⽆效的 token 访问时，服务端应该返回 401 错误码。

1 HTTP/1.1 401 Unauthorized
2 Content-Type: application/json
3 Cache-Control: no-store
4 Pragma: no-cache
5
6 {
7 "errcode":401001
8 "errmsg": "⽆效的令牌"
9 }