Rule 1. 使用名词表示资源

·使用名词来表示资源，而不是动词。例如，使用‘/users’而不是‘/getUsers’。

Rule 2. 使用复数形式

·对于表示多个资源的路径，通常使用复数形式。例如，‘/users’表示多个用户，而不是‘/user’。

Rule 3. 使用连字符分隔单词

·在路径中使用连字符(短横线)-来分隔单词，而不是下划线或驼峰式命名。例如，使用.

‘/user-profiles’而不是‘/userProfiles’或‘/user_profiles’；URI路径中全都使用小写字母 。

Rule 4. 嵌套资源

·对于嵌套资源，可以使用‘/resource/{id}/nested-resource’的形式。例如‘/users/{userId}/posts’表示特定用户的所有帖子。但是嵌套层数不宜过深，以保持其简洁性。

Rule 5. 使用HTTP方法表示操作

·使用 HTTP方法(GET、POST、PUT、DELETE等)来表示对资源的操作，而不是将操作动词包含在路径中。例如，使用‘GET /users’获取用户列表，而不是‘GET /getusers’。

Rule 6. 使用路径参数

·对于需要动态参数的路径，使用路径参数来表示。例如，‘/users/{userId}’表示特定用户的信息。路径参数只能使用主键或唯一标识

Rule 7. 版本控制

·对于 API的版本控制，可以将版本号包含在路径中。例如，‘/v1/users’表示 API的第一个版本的用户资源。

Rule 8. 保持简洁

·尽量保持路径简洁，避免过长和复杂的路径。路径应该清晰地表达资源和操作。

Rule 9. 分隔符

·正斜杠分隔符（/）用来指示层级关系

Rule 10. 排序(Sorting)

单个字段排序：

GET /v1/employee?sort=age&order=asc

GET /v1/employee?sort=age&order=desc

多个字段排序：

GET /v1/employee?sort=age,userName&order=asc,desc

Rule 11. 字段选择

调用方可能只需要资源的少量属性，接口提供方可支持客户端通过请求参数fields来选择返回的字段，多个字段以逗号分隔，示例如下：

GET /v1/employee?pageNum=1&pageSize=20&sort=age,name&order=desc,asc

或其它提交方法，只是要条件都可以放到参数后边。

Rule 12. 特殊操作

导出Excel文件

通常，导出操作是GET请求，因为它不会改变服务器上的状态，而是获取资源的表示。例如，要导出部门列表为Excel文件，可以使用如下URL：

GET http://localhost:8080/v1.0.0/departments/export

导入Excel文件

导入操作通常涉及客户端发送文件给服务器，这通常对应于POST或PUT请求。例如，要导入一个更新部门的Excel文件，可以使用如下URL：

POST http://localhost:8080/v1.0.0/departments/import

多文件上传

如果支持上传多个文件，可以使用POST请求，如下：

POST http://localhost:8080/v1.0.0/batch-import

Rule 13. 避免在URI中使用尾部斜杠

作为URI路径部分的最后一个字符，斜杠（/）不会增加语义价值，并可能导致混淆。最好是完全避免使用它们。

在RESTful架构中，一个URL代表一个资源，URL中可以包含多个参数，通过HTTP动词（GET、POST、PUT、DELETE等）来表示对资源的操作。以下是不同类型的 RESTful 接口示例：

描述	示例
获取用户列表	GET /users/list
创建新用户	POST /users
获取特定用户信息	GET /users/
更新特定用户信息	PUT /users/
删除特定用户	DELETE /users/
获取用户的订单列表	GET /users/{id}/orders/list
创建用户的新订单	POST /users/{id}/orders
获取特定订单信息	GET /orders/
更新特定订单信息	PUT /orders/
删除特定订单	DELETE /orders/
获取商品列表	GET /products/list
创建新商品	POST /products
获取特定商品信息	GET /products/
更新特定商品信息	PUT /products/
删除特定商品	DELETE /products/
获取商品的评论列表	GET /products/{productId}/reviews/list
创建新评论	POST /products/{productId}/reviews
获取特定评论信息	GET /reviews/
更新特定评论信息	PUT /reviews/
删除特定评论	DELETE /reviews/
用户登录	POST /login
用户登出	POST /logout
获取购物车信息	GET /users/{id}/cart
添加商品到购物车	POST /users/{id}/cart/items
更新购物车中的商品数量	PUT /users/{id}/cart/items/
删除购物车中的商品	DELETE /users/{id}/cart/items/
检查出库状态	GET /products/{productId}/shipments
创建商品出库记录	POST /products/{productId}/shipments
获取特定出库记录信息	GET /shipments/
更新特定出库记录信息	PUT /shipments/
删除特定出库记录	DELETE /shipments/
获取分类列表	GET /categories/list
创建新分类	POST /categories
获取特定分类信息	GET /categories/
更新特定分类信息	PUT /categories/
删除特定分类	DELETE /categories/
获取特定分类下的商品列表	GET /categories/{categoryId}/products/list
搜索商品	GET /products?query={searchTerm}
过滤商品	GET /products?price={minPrice}-{maxPrice}&category={categoryId}
排序商品	GET /products?sort={price,name,rating}&order={asc,desc}
获取优惠券列表	GET /coupons/list
创建新优惠券	POST /coupons
获取特定优惠券信息	GET /coupons/
更新特定优惠券信息	PUT /coupons/
删除特定优惠券	DELETE /coupons/
应用优惠券到购物车	POST /users/{id}/cart/coupons
移除购物车中的优惠券	DELETE /users/{id}/cart/coupons/
获取支付方式列表	GET /payments/list
创建新支付方式	POST /payments
获取特定支付方式信息	GET /payments/
获取退货列表	GET /returns/list
创建退货请求	POST /returns
获取特定退货请求信息	GET /returns/
更新特定退货请求信息	PUT /returns/
删除特定退货请求	DELETE /returns/
处理退货请求	PUT /returns/{returnId}/process
获取服务列表	GET /services/list
创建新服务	POST /services
获取特定服务信息	GET /services/
更新特定服务信息	PUT /services/
删除特定服务	DELETE /services/
获取服务的订单列表	GET /services/{serviceId}/orders/list
创建服务的新订单	POST /services/{serviceId}/orders
获取特定服务订单信息	GET /service-orders/
更新特定服务订单信息	PUT /service-orders/
删除特定服务订单	DELETE /service-orders/
获取服务提供商列表	GET /service-providers/list
创建新服务提供商	POST /service-providers
获取特定服务提供商信息	GET /service-providers/
更新特定服务提供商信息	PUT /service-providers/
删除特定服务提供商	DELETE /service-providers/
获取服务提供商的服务列表	GET /service-providers/{providerId}/services/list
获取通知列表	GET /notifications/list
创建新通知	POST /notifications
获取特定通知信息	GET /notifications/
更新特定通知信息	PUT /notifications/
删除特定通知	DELETE /notifications/
发送通知	POST /notifications/{notificationId}/send
获取设备列表	GET /devices/list
注册新设备	POST /devices
获取特定设备信息	GET /devices/
更新特定设备信息	PUT /devices/
删除特定设备	DELETE /devices/
获取用户的设备列表	GET /users/{id}/devices/list
用户添加新设备	POST /users/{id}/devices
获取用户的通知设置	GET /users/{id}/notification-settings
更新用户的通知设置	PUT /users/{id}/notification-settings
获取评价列表	GET /ratings/list
创建新评价	POST /ratings
获取特定评价信息	GET /ratings/
更新特定评价信息	PUT /ratings/
删除特定评价	DELETE /ratings/
获取用户的评价列表	GET /users/{id}/ratings/list
用户创建新评价	POST /users/{id}/ratings
获取用户的地址列表	GET /users/{id}/addresses/list
创建用户的新地址	POST /users/{id}/addresses
获取特定地址信息	GET /addresses/
更新特定地址信息	PUT /addresses/
删除特定地址	DELETE /addresses/
设置默认地址	PUT /users/{id}/addresses/{addressId}/default

示例参考链接：

Platform API Reference | Heroku Dev Center

@Api("部门信息表")
@RestController
@RequestMapping("/{version}/departments")
@ApiVersion
public class DepartmentsController {

    @Resource
    private DepartmentsService departmentsService;

    @ApiOperation(value = "根据id查询")
    @GetMapping("/{id}")//http://localhost:8080/v1.0.0/departments/1
    public Result<Department> getOne(@PathVariable Long id){
        Department department = departmentsService.queryOne(id);
        return R.ok(department);
    }

    @ApiOperation(value = "查询列表")
    @GetMapping("/list")//http://localhost:8080/v1.0.0/departments/list
    public Result<List<Department>> getList(DepartmentQuery department){
        List<Department> departmentList = departmentsService.list(department);
        return R.ok(departmentList);
    }

    @ApiOperation(value = "查询分页列表")
    @GetMapping("/page")//http://localhost:8080/v1.0.0/departments/page?pageNum=1&pageSize=10
    public Result<IPage<Department>> getPage(@RequestParam Integer pageNum, @RequestParam Integer pageSize){
        IPage<Department> departmentIPage = departmentsService.getPage(pageNum,pageSize);
        return R.ok(departmentIPage);
    }

    @ApiOperation(value = "新增")
    @PostMapping//http://localhost:8080/v1.0.0/departments
    public Result<Department> add(@RequestBody DepartmentCommand department){
        Department add = departmentsService.add(department);
        return R.ok(add);
    }

    @ApiOperation(value = "批量新增")
    @PostMapping("/batch")//http://localhost:8080/v1.0.0/departments/batch
    public Result<List<Department>> addList(@RequestBody List<DepartmentCommand> departments){
        List<Department> list = departmentsService.addList(departments);
        return R.ok(list);
    }

    @ApiOperation(value = "更新全量数据")
    @PutMapping("/{id}")//http://localhost:8080/v1.0.0/departments/1
    public Result<Department> update(@PathVariable Long id , @RequestBody DepartmentCommand department){
        Department update = departmentsService.update(id,department);
        return R.ok(update);
    }

    @ApiOperation(value = "更新部分数据")
    @PatchMapping("/{id}")//http://localhost:8080/v1.0.0/departments/1
    public Result<Department> updatePatch(@PathVariable Long id , @RequestBody DepartmentCommand department){
        Department patch = departmentsService.update(id,department);
        return R.ok(patch);
    }

    @ApiOperation(value = "批量更新数据")
    @PutMapping("/batch")//http://localhost:8080/v1.0.0/departments/batch
    public Result<List<Department>> updateBatch(@RequestBody List<DepartmentCommand> departments){
        List<Department> list = departmentsService.updateBatch(departments);
        return R.ok(list);
    }

    @ApiOperation(value = "删除")
    @DeleteMapping("/{id}")//http://localhost:8080/v1.0.0/departments/1
    public Result<?> delete(@PathVariable Long id){
        departmentsService.delete(id);
        return R.ok();
    }

    @ApiOperation(value = "批量删除")
    @DeleteMapping("/batch")//http://localhost:8080/v1.0.0/departments/batch?ids=1,2,3
    public Result<?> deleteByIds(@RequestParam List<Long> ids){
        departmentsService.deleteByIds(ids);
        return R.ok();
    }
    
    @ApiOperation(value = "导出excel")
    @GetMapping("/export")//http://localhost:8080/v1.0.0/departments/export?ids=1,2,3
    public Result<?> export(@RequestParam List<Long> ids){
        String fileName = departmentsService.export(ids);
        return R.ok(fileName);
    }

    @ApiOperation(value = "导入excel")
    @PostMapping("/import")//http://localhost:8080/v1.0.0/departments/import
    public Result<List<Department>> importExcel(MultipartFile multipartFile){
        List<Department> departmentList = departmentsService.importExcel(multipartFile);
        return R.ok(departmentList);
    }

    @ApiOperation(value = "查询某部门下的用户信息")
    @GetMapping("/{id}/users/list")//http://localhost:8080/v1.0.0/departments/1/users/list
    public Result<List<Users>> getUsers(@PathVariable Long id){
        List<Users> usersList = departmentsService.getUsers(id);
        return R.ok(usersList);
    }
    
    @ApiOperation(value = "查询某部门下的某个用户信息")
    @GetMapping("/{id}/users/{userId}")//http://localhost:8080/v1.0.0/departments/1/users/123
    public Result<Users> getUser(@PathVariable Long id,@PathVariable Long userId){
        Users user = departmentsService.getUser(id,userId);
        return R.ok(user);
    }
    
}