resful api 相关接口规范及案例演示

import cn.trasen.platform.opscloud.common.core.result.PlatformResult;
import cn.trasen.platform.opscloud.ops.client.api.entity.AccountEntity;
import cn.trasen.platform.opscloud.ops.client.api.entity.UserEntity;
import cn.trasen.platform.opscloud.ops.client.api.pojo.UserAddReqPojo;
import cn.trasen.platform.opscloud.ops.client.api.pojo.UserUpdateReqPojo;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import javax.validation.Valid;
import java.util.List;

@Slf4j
@RestController
@Api(tags = "用户管理")
@RequestMapping("/users")               // 定义复数，而不是 user
public class UserController {

    @Autowired
    private UserService userService;

    /**
     * 查询用户列表
     * @return
     */
    @ApiOperation("查询用户列表")
    @GetMapping                         // 当前对象的列表查询，不需要写路径
    public PlatformResult<List<UserEntity>> findUserList(){
        List<UserEntity> list = userService.findAll();
        return PlatformResult.success(list);
    }

    /**
     * 根据Id查询一个用户
     * @param id
     * @return
     */
    @ApiOperation("根据Id查询一个用户")
    @GetMapping(value = "/{id}")        // 使用path参数
    public PlatformResult<UserEntity> findUserOne(@PathVariable("id") Integer id){
        UserEntity userEntity = userService.findOne(id);
        return PlatformResult.success(userEntity);
    }

    /**
     * 添加用户
     * @param userAddReqPojo
     * @return
     */
    @ApiOperation("添加用户")
    @PostMapping                        // 当前对象的添加，不需要写路径
    public PlatformResult<Boolean> addUser(@Valid @RequestBody UserAddReqPojo userAddReqPojo){
        userService.save(user);
        return PlatformResult.success();
    }

    /**
     * 更新用户v
     * @param userUpdateReqPojo
     * @return
     */
    @ApiOperation("更新用户")
    @PutMapping(value = "/{id}")            // 指定id进行更新
    public PlatformResult<Boolean> updateUser(
        @ApiParam(name = "id",value = "参数id",required = true) @PathVariable Long id,
        @Valid @RequestBody UserUpdateReqPojo userUpdateReqPojo
    ){
        userService.save(userUpdateReqPojo);
        return PlatformResult.success();
    }

    /**
     * 更新用户<批量>
     * @param userUpdateReqPojos
     * @return
     */
    @ApiOperation("更新用户")
    @PutMapping(value = "/{id}")            // 指定id进行更新
    public PlatformResult<Boolean> updateUsers(@Valid @RequestBody UserUpdateReqPojo[] userUpdateReqPojos){
        userService.save(userUpdateReqPojos);
        return PlatformResult.success();
    }
    
    /**
     * 删除用户<单个>
     * @param id 用户id
     * @return
     */
    @ApiOperation("删除用户")
    @DeleteMapping(value = "/{id}")       // 使用path参数
    public PlatformResult<Boolean> deleteUser(@PathVariable("id") Integer id){
        userService.removeById(id);
        return PlatformResult.success();
    }

    /**
     * 删除用户<批量>
     * @param ids 用户id
     * @return
     */
    @ApiOperation("批量删除用户")
    // 必须增加 /batch 以区别 删除用户<单个> 的接口路径
    @DeleteMapping(value = "/batch/{ids}")       // 使用path参数
    public PlatformResult<Boolean> deleteUsers(@PathVariable("ids") List<Integer> ids){  // 请求示例：DELETE http://localhost:8080/users/batch/1234,1235,1236 也可以在前端框架中在 params 中自动转成 path 参数，自动填充到 url 上，参考：https://blog.csdn.net/swebin/article/details/124480360
        userService.removeByIds(ids);
        return PlatformResult.success();
    }

    /**
     * 根据用户id查询账户信息
     * @param id
     * @return
     */
    @ApiOperation("根据用户id查询账户信息")
    @GetMapping(value = "/{id}/accounts")   // 查询子资源信息
    public PlatformResult<List<AccountEntity>> findAccountByUserId(@PathVariable("id") String id){
        List<AccountEntity> list = userService.findAccountByUserId(id);
        return PlatformResult.success(list);
    }

    /**
     * 根据用户id、账户id，查询账户信息
     * @param id
     * @param account_id
     * @return
     */
    @ApiOperation("根据用户id、账户id，查询账户信息")
    @GetMapping(value = "/{id}/user_accounts/{account_id}")         // 如果需要区分，只能用_做区分，不要使用大写驼峰法区分
    public PlatformResult<AccountEntity> findAccount(@PathVariable("id") String id, @PathVariable("account_id") String account_id){
        AccountEntity accountEntity = userService.findAccount(id, account_id);
        return PlatformResult.success(accountEntity);
    }

}

总结：

URL只指定资源，以HTTP方法动词进行不同的操作，用HTTP STATUS/CODE定义操作结果。Restful：遵守了rest风格的web服务便可称为Restful

GET （查询用户）

POST（新增用户）

PUT（更新用户）

DELETE（删除用户）

（但是不排除有时候会违背resful接口规范，比如查询时前端要传大量筛选条件到后端时，后端不得不用RequestBody接收，因此不能用Get请求）