RESTful API 是后端接口的主流设计风格。好的 API 设计让前端用得舒服、后端维护省心、接口文档清晰。这篇总结在 SpringBoot 中实现 RESTful API 的规范和最佳实践。一、RESTful 核心原则资源Resource而不是动作Action ❌ /getUser?id1 ← 动词 参数 ❌ /deleteUser?id1 ← 动词 ❌ /user/add ← 动词 ✅ GET /users/{id} ← 查询用户 ✅ DELETE /users/{id} ← 删除用户 ✅ POST /users ← 新增用户 ✅ PUT /users/{id} ← 修改用户HTTP 动词与 CRUD 对应方法操作示例说明GET查询GET /users获取用户列表GET查询GET /users/1获取单个用户POST新增POST /users新增用户PUT全量修改PUT /users/1替换用户信息PATCH部分修改PATCH /users/1修改用户部分字段DELETE删除DELETE /users/1删除用户二、URL 设计规范1. 命名规范// 名词复数形式不要动词/api/users// ✅/api/getUserList// ❌// 层级用 / 表示/users/{uid}/orders// 用户的订单/users/{uid}/orders/{oid}// 用户的某个订单// 查询参数用于过滤、排序、分页GET/users?page1size20sortcreateTime,desc2. Controller 示例RestControllerRequestMapping(/api/users)publicclassUserController{GetMappingpublicResultVOPageUserlist(RequestParam(defaultValue1)intpage,RequestParam(defaultValue20)intsize,RequestParam(requiredfalse)Stringkeyword){// GET /api/users?page1size20keyword张returnResultVO.success(userService.page(page,size,keyword));}GetMapping(/{id})publicResultVOUserget(PathVariableLongid){// GET /api/users/1returnResultVO.success(userService.getById(id));}PostMappingpublicResultVOUsercreate(RequestBodyValidUseruser){// POST /api/usersuserService.save(user);returnResultVO.success(user);}PutMapping(/{id})publicResultVOUserupdate(PathVariableLongid,RequestBodyValidUseruser){// PUT /api/users/1user.setId(id);userService.updateById(user);returnResultVO.success(user);}DeleteMapping(/{id})publicResultVO?delete(PathVariableLongid){// DELETE /api/users/1userService.removeById(id);returnResultVO.success(删除成功);}}三、统一响应格式所有接口返回统一的 JSON 结构前端不用处理多种格式。DataAccessors(chaintrue)publicclassResultVOT{privateintcode;privateStringmessage;privateTdata;privatelongtimestamp;publicResultVO(){this.timestampSystem.currentTimeMillis();}publicstaticTResultVOTsuccess(Tdata){returnnewResultVOT().setCode(200).setMessage(操作成功).setData(data);}publicstaticTResultVOTerror(intcode,Stringmessage){returnnewResultVOT().setCode(code).setMessage(message);}}统一响应示例// 成功{code:200,message:操作成功,data:{id:1,name:张三},timestamp:1712345678000}// 失败{code:400,message:参数错误用户名为空,data:null,timestamp:1712345678000}四、参数校验1. 常用注解DatapublicclassUserCreateDTO{NotBlank(message用户名不能为空)Size(min2,max20,message用户名长度2-20)privateStringusername;NotBlank(message密码不能为空)Size(min6,max32,message密码长度6-32)privateStringpassword;Email(message邮箱格式不正确)privateStringemail;Pattern(regexp^1[3-9]\\d{9}$,message手机号格式不正确)privateStringphone;Min(value0,message年龄不能小于0)Max(value150,message年龄不能大于150)privateIntegerage;}2. 分组校验// 不同操作使用不同校验规则publicinterfaceCreateGroup{}publicinterfaceUpdateGroup{}DatapublicclassUserDTO{Null(groupsCreateGroup.class,message新增时ID必须为空)NotNull(groupsUpdateGroup.class,message修改时ID不能为空)privateLongid;NotBlank(message用户名不能为空)privateStringname;}// ControllerPostMappingpublicResultVO?create(RequestBodyValidated(CreateGroup.class)UserDTOdto){returnResultVO.success(userService.create(dto));}PutMapping(/{id})publicResultVO?update(RequestBodyValidated(UpdateGroup.class)UserDTOdto){returnResultVO.success(userService.update(dto));}3. 全局异常处理RestControllerAdvicepublicclassGlobalExceptionHandler{// 参数校验异常ExceptionHandler(MethodArgumentNotValidException.class)publicResultVO?handleValidation(MethodArgumentNotValidExceptione){Stringmsge.getBindingResult().getFieldErrors().stream().map(FieldError::getDefaultMessage).collect(Collectors.joining());returnResultVO.error(400,msg);}// 业务异常ExceptionHandler(BusinessException.class)publicResultVO?handleBusiness(BusinessExceptione){returnResultVO.error(e.getCode(),e.getMessage());}// 其他异常ExceptionHandler(Exception.class)publicResultVO?handleOther(Exceptione){log.error(系统异常,e);returnResultVO.error(500,服务器内部错误);}}五、分页接口规范GetMappingpublicResultVOPageResultUserVOlist(RequestParam(defaultValue1)intpage,RequestParam(defaultValue20)intsize){PageUserpageResultuserService.page(newPage(page,size));PageResultUserVOresultnewPageResult();result.setPage(page);result.setSize(size);result.setTotal(pageResult.getTotal());result.setPages(pageResult.getPages());result.setList(userMapper.toVOList(pageResult.getRecords()));returnResultVO.success(result);}{code:200,data:{page:1,size:20,total:156,pages:8,list:[...]}}六、API 版本管理// 方案一URL 路径版本RestControllerRequestMapping(/api/v1/users)publicclassUserControllerV1{}RestControllerRequestMapping(/api/v2/users)publicclassUserControllerV2{}// 方案二自定义注解Target(ElementType.TYPE)Retention(RetentionPolicy.RUNTIME)publicinterfaceApiVersion{intvalue()default1;}七、Swagger 文档RestControllerRequestMapping(/api/users)Tag(name用户管理,description用户增删改查接口)publicclassUserController{GetMapping(/{id})Operation(summary查询用户,description根据ID获取用户详细信息)publicResultVOUserget(Parameter(description用户ID)PathVariableLongid){returnResultVO.success(userService.getById(id));}PostMappingOperation(summary新增用户)publicResultVOUsercreate(RequestBodyValidValidated(CreateGroup.class)UserCreateDTOdto){returnResultVO.success(userService.create(dto));}}八、接口安全建议// 1. 敏感信息不返回JsonIgnoreprivateStringpassword;// 2. 接口限流RateLimit(keyuser:list,max10,window1)// 3. 权限控制PreAuthorize(hasRole(ADMIN))// 4. 输入过滤Pattern(regexp^[a-zA-Z0-9_]$)九、完整接口示例RestControllerRequestMapping(/api/v1/products)Tag(name商品管理)publicclassProductController{GetMappingOperation(summary分页查询商品)publicResultVOPageResultProductVOlist(ProductQueryDTOquery){returnResultVO.success(productService.queryPage(query));}GetMapping(/{id})Operation(summary获取商品详情)publicResultVOProductVOget(PathVariableLongid){returnResultVO.success(productService.getDetail(id));}PostMappingOperation(summary新增商品)publicResultVOProductVOcreate(RequestBodyValidProductCreateDTOdto){returnResultVO.success(productService.create(dto));}PutMapping(/{id})Operation(summary修改商品)publicResultVOProductVOupdate(PathVariableLongid,RequestBodyValidProductUpdateDTOdto){dto.setId(id);returnResultVO.success(productService.update(dto));}DeleteMapping(/{id})Operation(summary删除商品)publicResultVO?delete(PathVariableLongid){productService.delete(id);returnResultVO.success(删除成功);}PatchMapping(/{id}/stock)Operation(summary修改库存)publicResultVO?updateStock(PathVariableLongid,RequestParamintstock){productService.updateStock(id,stock);returnResultVO.success(修改成功);}}总结RESTful API 设计记住三句话URL 用名词复数不用动词 HTTP 方法对应 CRUD 操作 返回统一的 JSON 结构API 设计是后端的基本功好的 API 设计让前后端协作事半功倍。 觉得有用的话点赞 关注【张老师技术栈】吧每周更新 Java/Python/爬虫 实战干货不让你白来。