URL是API的第一张名片，好的URL设计让开发者一眼就能理解接口的功能和资源关系。本文结合实际项目案例，分享API URL设计的核心原则和常见场景的落地方案。
资源路径设计
URL路径反映资源的层级关系。顶级资源如 /users、/orders、/products 直接对应业务实体。子资源通过路径嵌套表达从属关系，如 /users/{userId}/addresses 表示用户的地址列表。关联资源如果跨层级，可以直接在URL中表达多级嵌套，但不要超过三层。对于深层资源，可以考虑拆分到独立的端点，或者通过查询参数来定位。
过滤与排序
查询参数用于过滤和排序资源列表。过滤参数直接使用字段名作为参数名，如 /products?category=electronics&price=100-500。范围查询用 min 和 max 前缀，如 ?priceMin=100&priceMax=500。排序用 sortBy 指定排序字段，sortOrder 指定升序降序，如 ?sortBy=createTime&sortOrder=desc。多字段排序用逗号分隔，如 ?sortBy=createTime,price&sortOrder=desc,asc。
分页设计
列表接口必须支持分页。推荐使用基于偏移量的分页方式，参数为 page 和 pageSize。page 从1开始，pageSize 默认20，最大不超过100。响应中返回 total 总数和当前页数据。对于大数据量场景，基于游标的分页性能更好，使用 cursor 参数替代 page。游标分页适用于无限滚动和实时数据场景，能避免偏移量分页在数据变更时的重复或遗漏问题。
URL版本管理
API版本管理有URL前缀版本和请求头版本两种方式。URL前缀版本更直观，如 /v1/users、/v2/users。版本号使用整数，不需要使用 v1.2 这种语义化版本。版本迭代时，向后兼容的变更不需要升级版本号，只有破坏性变更才需要升级主版本。推荐至少维护一个大版本的向后兼容，给客户端留出足够的迁移时间。