restful风格接口命名规范

（一）rest

1.概念

REST即表述性状态传递（英文：Representational State Transfer，简称REST）是Roy Fielding博士在2000年他的博士论文中提出来的一种软件架构风格。它是一种针对网络应用的设计和开发方式，可以降低开发的复杂性，提高系统的可伸缩性。

可理解为：URL定位资源，用HTTP动词（GET,POST,DELETE,DETC）描述操作。

语法：

URI = scheme "://" authority "/" path [ "?" query ][ "#" fragment ]

• scheme: 指底层用的协议，如http、https、ftp。
• host: 服务器的IP地址或者域名。
• port: 端口，http中默认80。
• path: 访问资源的路径，就是各种 WEB 框架中定义的 Route 路由。
• query: 为发送给服务器的参数。
• fragment: 锚点，定位到页面的资源，锚点为资源 id。

项目中应使用：

URI = scheme"://"authority"/"api"/"version"/"path["?"query]["#"fragment]

2.restful

复合rest风格的接口

3.http常用方法

• get：获取数据
• post：插入数据
• put：修改数据
• delete：删除数据

4.名词

例如CSDN某请求接口：

https://msg.csdn.net/v1/web/message/view/unread

v1代表版本号，可以发现他的接口都是名词，所以可以知道restful接口使用的是名词。

例如设计一个获取数据的接口可以这样设计：/v1/list

上面为获取所有数据，当需要获取某一条数据时，可以这样设计：/v1/list/1,代表获取id为1的数据。

5.用法

可以设计出增删改查的restful接口：

• 获取：v1/list–>GET
• 添加：v1/list–>POST
• 修改：v1/list–>PUT
• 删除：v1/list–>DELETE

6.应用

@RestController
@RequestMapping("api")
@CrossOrigin
public class HelloController {
    @Autowired
    private UserService service;

    /**
     * 获取全部列表
     * @return
     */
    @GetMapping("/v1/list")
    public String getList(){
        return "获取全部列表";
    }

    /**
     * 获取列表中的一条
     * @param id 通过id获取数据
     * @return
     */
    @GetMapping("/v1/list/{id}")
    public String getListOne(@PathVariable (value = "id") Integer id){
        return "获取列表中的" + id;
    }

    /**
     * 往列表中添加数据
     * @return
     */
    @PostMapping("/v1/list")
    public String insert(){
        return "往列表中添加数据";
    }

    /**
     * 修改列表数据
     * @param id 修改该列表的id
     * @return
     */
    @PutMapping("/v1/list/{id}")
    public String update(@PathVariable(value = "id") Integer id){
        return "修改列表数据" + id;
    }

    /**
     * 删除列表数据
     * @return
     */
    @DeleteMapping("/v1/list")
    public String delete(){
        return "删除列表数据";
    }
}

7.特点

• 基于“资源”，数据也好、服务也好，在RESTFul设计里一切都是资源。
• 无状态。一次调用一般就会返回结果，不存在类似于“打开连接-访问数据-关闭连接”这种依赖于上一次调用的情况。
• URL中通常不出现动词，只有名词 。
• URL语义清晰、明确 。
• 使用HTTP的GET、POST、DELETE、PUT来表示对于资源的增删改查 。
• 使用JSON不使用XML 。

8.最佳实践原则

• 使用HTTP动词表示增删改查资源， GET：查询，POST：新增，PUT：更新，DELETE：删除 。
• 返回结果必须使用JSON 。
• HTTP状态码，在REST中都有特定的意义：200，201,202,204,400,401,403,500。比如401表示用户身份认证失败，403表示你验证身份通过了，但这个资源你不能操作。
• API必须有版本的概念，v1，v2，v3 。
• 使用Token令牌来做用户身份的校验与权限分级，而不是Cookie。
• url中大小写不敏感，不要出现大写字母。
• 使用 - 而不是使用 _ 做URL路径中字符串连接。
• url结尾不应该包含斜杠"/"
• url路径名词均为复数