[点晴永久免费OA]Restful API接口规范

当前位置：点晴教程→点晴OA办公管理信息系统 →『经验分享&问题答疑』

admin

2022年4月18日 16:6 本文热度 1250

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);
    }
}

该文章在 2022/4/18 16:06:58 编辑过

关键字查询

接口

正在查询...

点晴ERP是一款针对中小制造业的专业生产管理软件系统,系统成熟度和易用性得到了国内大量中小企业的青睐。

点晴PMS码头管理系统主要针对港口码头集装箱与散货日常运作、调度、堆场、车队、财务费用、相关报表等业务管理，结合码头的业务特点，围绕调度、堆场作业而开发的。集技术的先进性、管理的有效性于一体，是物流码头及其他港口类企业的高效ERP管理信息系统。

点晴WMS仓储管理系统提供了货物产品管理,销售管理,采购管理,仓储管理,仓库管理,保质期管理,货位管理,库位管理,生产管理,WMS管理系统,标签打印,条形码,二维码管理,批号管理软件。

点晴免费OA是一款软件和通用服务都免费，不限功能、不限时间、不限用户的免费OA协同办公管理系统。