编码规范学习

最新推荐文章于 2024-07-08 17:49:05 发布

草莓盼盼是胖胖

最新推荐文章于 2024-07-08 17:49:05 发布

阅读量75

点赞数

分类专栏： java swagger 文章标签： restful java api

原文链接：https://blog.csdn.net/qq_35075909/article/details/91522242

版权

java 同时被 2 个专栏收录

32 篇文章 0 订阅

订阅专栏

swagger

3 篇文章 0 订阅

订阅专栏

controller层

1 所有函数返回统一的ResultBean/PageResultBean格式

public class ResponseBean<T> {
    private int code;

    private String description = "";

    private long lastUpdateTime;

    private T data;
}

2 Controller做参数格式的转换，不允许把json，map这类对象传到services去，也不允许services返回json、map。
3 参数中一般情况不允许出现Request，Response这些对象

方法命名

url

REST 描述了 HTTP 层里客户端和服务器端的数据交互规则；客户端通过向服务器端发送 HTTP（s）请求，接收服务器的响应，完成一次 HTTP 交互。这个交互过程中，REST 架构约定两个重要方面就是HTTP请求的所采用方法，以及请求的链接。因此，REST 规范可以简单粗暴抽象成以下两个规则：

请求 API 的 URL 表示用来定位资源；
请求的 METHOD 表示对这个资源进行的操作；

URL 用来定位资源，跟要进行的操作区分开，这就意味着URL不该有任何动词。下面示例中的 get、create、search 等动词，都不应该出现在 REST 架构的后端接口路径中。比如：

/api/getUser
/api/createApp
/api/searchResult
/api/deleteAllUsers

一、样例

1.URL 中应该单复数区分，推荐的实践是永远只用复数；如下表示获取用户的列表；

GET /api/users

2.如果获取单个资源，传入 ID，如下，表示获取单个用户的信息；

/api/users/123

3.按照资源的逻辑层级，对 URL 进行嵌套，比如一个用户属于某个团队，而这个团队也是众多团队之一；那么获取这个用户的接口可能是这样：表示获取 id 为 123 的小组下，id 为234 的成员信息。

GET /api/teams/123/members/234

按照类似的规则，可以写出如下的接口

/api/teams （对应团队列表）
/api/teams/123 （对应 ID 为 123 的团队）
/api/teams/123/members （对应 ID 为 123 的团队下的成员列表）
/api/teams/123/members/456 （对应 ID 为 123 的团队下 ID 未 456 的成员）

二、正确示例

标准的格式是

http(s): //server.com /app-name /{version} /{domain} /{rest-convention}

{version}代表api的版本信息。
{domain}是一个你可以用来定义任何技术的区域(例如：安全-允许指定的用户可以访问这个区域)或者业务上的原因(例如：同样的功能在同一个前缀之下。)
{rest-convention} 代表这个域(domain)下，约定的rest接口集合。

单资源( singular-resourceX )
url样例：order/ (order即指那个单独的资源X)
GET – 返回一个新的order
POST- 创建一个新的order，从post请求携带的内容获取值。

单资源带id(singular-resourceX/{id} )
URL样例：order/1 ( order即指那个单独的资源X )
GET – 返回id是1的order
DELETE – 删除id是1的order
PUT – 更新id是1的order，order的值从请求的内容体中获取。

复数资源(plural-resourceX/)
URL样例:orders/
GET – 返回所有orders

复数资源查找(plural-resourceX/search)
URL样例：orders/search?name=123
GET – 返回所有满足查询条件的order资源。(实例查询，无关联) – order名字等于123的。

复数资源查找(plural-resourceX/searchByXXX)
URL样例：orders/searchByItems?name=ipad
GET – 将返回所有满足自定义查询的orders – 获取所有与items名字是ipad相关联的orders。

单数资源(singular-resourceX/{id}/pluralY)
URL样例：order/1/items/ (这里order即为资源X，items是复数资源Y)
GET – 将返回所有与order id 是1关联的items。

singular-resourceX/{id}/singular-resourceY/
URL样例：order/1/item/
GET – 返回一个瞬时的新的与order id是1关联的item实例。
POST – 创建一个与order id 是1关联的item实例。Item的值从post请求体中获取。

singular-resourceX/{id}/singular-resourceY/{id}/singular-resourceZ/
URL样例：order/1/item/2/package/
GET – 返回一个瞬时的新的与item2和order1关联的package实例。
POST – 创建一个新的与item 2和order1关联的package实例，package的值从post请求体中获得。