Restful API接口规范

时间:2024-10-27 07:17:44

简介

REST:英文representational state transfer直译为表现层状态转移,或者表述性状态转移;Rest是web服务的一种架构风格,一种设计风格,是一种思想;同时Rest不是针对某一种编程语言的。

以webService为例通俗解释。

非Rest设计,以往我们都会这么写:

http://localhost:8080/admin/getUser (查询用户)

http://localhost:8080/admin/addUser (新增用户)

http://localhost:8080/admin/updateUser (更新用户)

http://localhost:8080/admin/deleteUser (删除用户)

总结:以不同的URL(主要为使用动词)进行不同的操作。

 

Rest架构:

GET http://localhost:8080/admin/user (查询用户)

POST http://localhost:8080/admin/user (新增用户)

PUT http://localhost:8080/admin/user (更新用户)

DELETE http://localhost:8080/admin/user (删除用户)

总结:URL只指定资源,以HTTP方法动词进行不同的操作。用HTTP STATUS/CODE定义操作结果。

 

Restful:遵守了rest风格的web服务便可称为Restful。

 

为什么需要Restful?

 

URL具有很强可读性的,具有自描述性

规范化请求过程和返回结果

资源描述与视图的松耦合

可提供OpenAPI,便于第三方系统集成,提高互操作性

提供无状态的服务接口,降低复杂度,可提高应用的水平扩展性

 

/版本号/资源路径

/v1/tags/{tag_id}

/v1/users?[&keyword=xxx][&enable=1][&offset=0][&limit=20]

 

1、版本号

命名版本号可以解决版本不兼容问题,在设计 RESTful API 的一种实用的做法是使用版本号。一般情况下,我们会在 url 中保留旧版本号,并同时兼容多个版本

【GET】  /v1/users/{user_id}  // 版本 v1 的查询用户列表的 API 接口

【GET】  /v2/users/{user_id}  // 版本 v2 的查询用户列表的 API 接口

 

2、资源路径

URI 不能包含动词,只能是名词(命名名词的时候,要使用小写、数字及下划线来区分多个单词)。

资源的路径应该从根到子依次如下:

/{resources}/{resource_id}/{sub_resources}/{sub_resource_id}/{sub_resource_property}

【POST】  /v1/users/{user_id}/roles/{role_id} // 添加用户的角色

 

有的时候,当一个资源变化难以使用标准的 RESTful API 来命名,可以考虑使用一些特殊的 actions 命名。

/{resources}/{resource_id}/actions/{action}

【PUT】  /v1/users/{user_id}/password/actions/modify // 密码修改

 

3、请求方式

【GET】          /users                # 查询用户信息列表

【GET】          /users/1001           # 查看某个用户信息

【POST】         /users                # 新建用户信息

【PUT】          /users/1001           # 更新用户信息(全部字段)

【PATCH】        /users/1001           # 更新用户信息(部分字段)

【DELETE】       /users/1001           # 删除用户信息

 

【PATCH】一般不用,用【PUT】

 

4、查询参数

RESTful API 接口应该提供参数,过滤返回结果。

【GET】  /{version}/{resources}/{resource_id}?offset=0&limit=20

 

5、响应参数

JSON格式(code、data、msg)

 

6、状态码

使用适合的状态码很重要,而不应该全部都返回状态码 200

状态码,可根据以下标准按照项目扩展自身状态码:

200~299段 表示操作成功:

200 操作成功,正常返回

201 操作成功,已经正在处理该请求

300~399段 表示参数方面的异常

300 参数类型错误

301 参数格式错误

302 参数超出正常取值范围

303 token过期

304 token无效

400~499段 表示请求地址方面的异常:

400 找不到地址

500~599段 表示内部代码异常:

500 服务器代码异常

 

7、完整事例

 

 

@RestController(/v1)

@API(tag=”用户相关接口”)

public class UserController {

 

    @Autowired

    private UserJPARepository userJPARepository;

 

    /**

     * 查询用户列表

     * @return

     */

    @GetMapping(value = "/user")

    public List<User> findUserList(){

        return ();

    }

 

    /**

     * 根据Id查询一个用户

     * @param id

     * @return

     */

    @GetMapping(value = "/user/query/{id}")

    public User findUserOne(@PathVariable("id") Integer id){

        return (id);

    }

 

    /**

     * 添加用户

     * @param name

     * @param age

     * @param country

     * @return

     */

 

    @PostMapping(value = "/user")

    public User addUser(@RequestParam("name") String name, @RequestParam("age") int age,

                        @RequestParam("country") String country){

        User user = new User();

        (name);

        (age);

        (country);

        return (user);

    }

 

    /**

     * 删除用户

     * @param id  用户编号

     * @return

     */

    @DeleteMapping(value = "/user/{id}")

    public  List<User> deleteUser(@PathVariable("id") Integer id){

        (id);

        return ();

    }

 

    /**

     * 更新用户

     * @param id

     * @param name

     * @param age

     * @param country

     * @return

     */

    @PutMapping(value = "/user/{id}")

    public User updateUser(@PathVariable("id") Integer id, @RequestParam("name") String name,

                           @RequestParam("age") int age, @RequestParam("country") String country){

        User user = (id);

        (name);

        (age);

        (country);

        return (user);

    }

 

    /**

     * 根据国家查询用户

     * @param country

     * @return

     */

    @GetMapping(value = "/user/{country}")

    public List<User> findByCountry(@PathVariable("country") String country){

        return (country);

    }

}