1. 引言RESTful URL 是构建 Web API 的核心设计要素之一。一个设计良好的 URL 不仅能让接口易于理解和维护还能显著提升开发协作效率。本文将从 REST 的基本概念出发结合丰富的代码实例系统讲解 RESTful URL 的设计规范与最佳实践。2. REST 与 URL 基础RESTRepresentational State Transfer是一种基于 HTTP 协议的架构风格。在 REST 架构中URL 用于标识资源HTTP 方法用于定义对资源的操作。理解这一对应关系是设计 RESTful URL 的前提。HTTP 方法操作语义典型场景GET读取资源查询列表、获取详情POST创建资源新增一条记录PUT整体更新替换整个资源PATCH局部更新修改部分字段DELETE删除资源移除一条记录3. URL 命名规范RESTful URL 的命名应遵循以下核心原则使用名词而非动词、使用复数形式、使用小写字母和连字符。下面通过对比示例说明。3.1 使用名词而非动词URL 表示资源不应包含操作动词。操作语义应由 HTTP 方法表达。# 不推荐动词出现在 URL 中 GET /getUser POST /createOrder DELETE /removeProduct 推荐URL 只描述资源 GET /users POST /orders DELETE /products/423.2 使用复数名词集合资源统一使用复数形式保持接口风格一致。# 不推荐 GET /user/1 GET /order/100 推荐 GET /users/1 GET /orders/1003.3 小写字母与连字符URL 统一使用小写字母多词组合用连字符分隔避免使用下划线或驼峰命名。# 不推荐 GET /userProfile GET /user_profile 推荐 GET /user-profiles4. 资源层级与嵌套当资源之间存在从属关系时可以通过 URL 层级表达。但嵌套层级不宜过深一般建议不超过两层。// 嵌套资源示例查询某用户的所有订单 GetMapping(/users/{userId}/orders) public ListOrder getUserOrders(PathVariable Long userId) { return orderService.findByUserId(userId); } // 查询某用户某个具体订单 GetMapping(/users/{userId}/orders/{orderId}) public Order getUserOrder(PathVariable Long userId, PathVariable Long orderId) { return orderService.findByUserAndOrder(userId, orderId); }如果嵌套层级过深建议将子资源提升为独立资源通过查询参数关联。# 不推荐层级过深 GET /users/1/orders/2/items/3 推荐子资源独立 GET /order-items?orderId25. 查询参数的使用查询参数用于过滤、排序、分页和字段选择。合理使用查询参数可以显著提升 API 的灵活性和复用性。5.1 过滤与排序# Flask 示例支持过滤、排序和分页 from flask import Flask, request, jsonify app Flask(name) app.route(/api/products, methods[GET]) def get_products(): # 过滤条件 category request.args.get(category) min_price request.args.get(min_price, typefloat) # 排序 sort_by request.args.get(sort_by, id) order request.args.get(order, asc) 分页 page request.args.get(page, default1, typeint) page_size request.args.get(page_size, default20, typeint) query Product.query if category: query query.filter(Product.category category) if min_price is not None: query query.filter(Product.price gt; min_price) if order desc: query query.order_by(getattr(Product, sort_by).desc()) else: query query.order_by(getattr(Product, sort_by).asc()) products query.paginate(pagepage, per_pagepage_size) return jsonify({ items: [p.to_dict() for p in products.items], total: products.total, page: page, page_size: page_size })/code/pre 5.2 字段选择 只返回指定字段减少传输数据量 GET /users/1?fieldsid,name,email 响应示例 { id: 1, name: 张三, email: zhangsanexample.com } 6. 完整实战示例 下面通过一个完整的 Spring Boot 项目演示 RESTful URL 的落地实现。 6.1 控制器定义 RestController RequestMapping(/api/v1/users) public class UserController { Autowired private UserService userService; // GET /api/v1/users —— 查询用户列表 GetMapping public PageResultlt;Usergt; listUsers( RequestParam(defaultValue 1) int page, RequestParam(defaultValue 20) int pageSize, RequestParam(required false) String keyword) { return userService.listUsers(page, pageSize, keyword); } // GET /api/v1/users/{id} —— 查询单个用户 GetMapping(/{id}) public User getUser(PathVariable Long id) { return userService.getUser(id); } // POST /api/v1/users —— 创建用户 PostMapping ResponseStatus(HttpStatus.CREATED) public User createUser(RequestBody Valid UserCreateRequest request) { return userService.createUser(request); } // PUT /api/v1/users/{id} —— 整体更新用户 PutMapping(/{id}) public User updateUser(PathVariable Long id, RequestBody Valid UserUpdateRequest request) { return userService.updateUser(id, request); } // PATCH /api/v1/users/{id} —— 局部更新用户 PatchMapping(/{id}) public User patchUser(PathVariable Long id, RequestBody Maplt;String, Objectgt; fields) { return userService.patchUser(id, fields); } // DELETE /api/v1/users/{id} —— 删除用户 DeleteMapping(/{id}) ResponseStatus(HttpStatus.NO_CONTENT) public void deleteUser(PathVariable Long id) { userService.deleteUser(id); } } 6.2 客户端调用示例 // JavaScript 客户端调用示例 const API_BASE /api/v1/users; // 创建用户 const createUser async (userData) { const response await fetch(API_BASE, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify(userData) }); return response.json(); }; // 查询用户列表带分页和过滤 const listUsers async (page 1, keyword ) { const params new URLSearchParams({ page, page_size: 20 }); if (keyword) params.append(keyword, keyword); const response await fetch(${API_BASE}?${params}); return response.json(); }; // 局部更新用户 const patchUser async (id, fields) { const response await fetch(${API_BASE}/${id}, { method: PATCH, headers: { Content-Type: application/json }, body: JSON.stringify(fields) }); return response.json(); }; 7. 常见错误与规避 在实际开发中以下 URL 设计问题最为常见需要特别注意规避。 动词出现在 URL 中如 /getUsers应改为 GET /users。 层级嵌套过深超过两层的嵌套会显著增加 URL 复杂度和维护成本。 大小写混用URL 应统一小写避免 /UserProfile 这类写法。 使用下划线多词组合应使用连字符如 /user-profiles 而非 /user_profiles。 忽略 HTTP 状态码URL 设计正确的同时还应配合恰当的 HTTP 状态码表达操作结果。 8. 总结 RESTful URL 设计的核心在于「资源导向」用名词描述资源、用 HTTP 方法表达操作、用查询参数处理筛选和分页。遵循这些规范可以让 API 更加直观、一致且易于维护。建议在项目初期就制定团队统一的 URL 规范并在代码评审中持续把关。