[点晴永久免费OA]Restful API接口规范
当前位置：点晴OA办公管理信息系统
→『 经验分享&问题答疑 』
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 编辑过 |
关键字查询
相关文章
正在查询... 
|
400 186 1886
