zoukankan      html  css  js  c++  java
  • Restful API接口规范

    一、简介

    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、完整事例

    UserController.java

    @RestController(/v1)
    
    @API(tag=”用户相关接口”)
    
    public class UserController {
    
     
    
        @Autowired
    
        private UserJPARepository userJPARepository;
    
     
    
        /**
    
         * 查询用户列表
    
         * @return
    
         */
    
        @GetMapping(value = "/user")
    
        public List<User> findUserList(){
    
            return userJPARepository.findAll();
    
        }
    
     
    
        /**
    
         * 根据Id查询一个用户
    
         * @param id
    
         * @return
    
         */
    
        @GetMapping(value = "/user/query/{id}")
    
        public User findUserOne(@PathVariable("id") Integer id){
    
            return userJPARepository.findOne(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();
    
            user.setName(name);
    
            user.setAge(age);
    
            user.setCountry(country);
    
            return userJPARepository.save(user);
    
        }
    
     
    
        /**
    
         * 删除用户
    
         * @param id  用户编号
    
         * @return
    
         */
    
        @DeleteMapping(value = "/user/{id}")
    
        public  List<User> deleteUser(@PathVariable("id") Integer id){
    
            userJPARepository.delete(id);
    
            return userJPARepository.findAll();
    
        }
    
     
    
        /**
    
         * 更新用户
    
         * @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 = userJPARepository.findById(id);
    
            user.setName(name);
    
            user.setAge(age);
    
            user.setCountry(country);
    
            return userJPARepository.save(user);
    
        }
    
     
    
        /**
    
         * 根据国家查询用户
    
         * @param country
    
         * @return
    
         */
    
        @GetMapping(value = "/user/{country}")
    
        public List<User> findByCountry(@PathVariable("country") String country){
    
            return userJPARepository.findByCountry(country);
    
        }
    
    }
  • 相关阅读:
    Java实现 蓝桥杯VIP 算法提高 P0404
    Java实现 蓝桥杯VIP 算法提高 P0404
    Java实现 蓝桥杯VIP 算法提高 P0404
    Java实现 蓝桥杯VIP 算法提高 P0404
    Java实现 蓝桥杯VIP 算法提高 P0404
    Java实现 蓝桥杯VIP 算法训练 排列问题
    Java实现 蓝桥杯VIP 算法训练 排列问题
    Java实现 蓝桥杯VIP 算法训练 排列问题
    Java实现 蓝桥杯VIP 算法训练 排列问题
    关于模态/非模态对话框不响应菜单的UPDATE_COMMAND_UI消息(对对WM_INITMENUPOPUP消息的处理)
  • 原文地址:https://www.cnblogs.com/geass-jango/p/11429153.html
Copyright © 2011-2022 走看看