本文详解在 Spring 项目中为“获取当前用户媒体”场景选择合理 API 端点的原则，推荐采用资源中心化 + 查询参数过滤的设计（如 /medias?owner=me），而非新增专属路径，兼顾规范性、可扩展性与维护性。
本文详解在 spring 项目中为“获取当前用户媒体”场景选择合理 api 端点的原则，推荐采用资源中心化 + 查询参数过滤的设计（如 `/medias?owner=me`），而非新增专属路径，兼顾规范性、可扩展性与维护性。
在构建 RESTful API 时，端点（Endpoint）的设计不仅影响接口的可读性与一致性，更直接关系到系统的可维护性、可扩展性及团队协作效率。面对“获取当前用户媒体”这一常见需求，你提出的两个选项——/users/me/medias（置于 UserController）和 /medias/me（置于 MediaController）——看似语义相近，实则隐含了不同的架构意图与潜在技术债务。
✅ 推荐方案：资源导向 + 查询参数过滤
端点形式：GET /medias?owner=me
将该功能实现在 MediaController 中，并复用已有的媒体列表接口（如 GET /medias），通过标准查询参数（如 owner, type, status, page, size）实现动态筛选：
@RestController
@RequestMapping("/medias")
public class MediaController {
@GetMapping
public ResponseEntity<List<Media>> listMedias(
@RequestParam(required = false) String owner,
@RequestParam(required = false) String type,
@RequestParam(defaultValue = "0") int page,
@RequestParam(defaultValue = "20") int size) {
// 若 owner="me"，自动解析为当前认证用户 ID
Long userId = "me".equals(owner) ? getCurrentUserId() : null;
List<Media> medias = mediaService.findByOwnerAndType(userId, type, page, size);
return ResponseEntity.ok(medias);
}
}✅ 优势说明：
-
符合 REST 资源中心化原则：
/medias是媒体资源的唯一权威入口，所有媒体相关操作（增删改查、筛选、分页）均围绕该路径展开； -
天然支持组合过滤：后续增加
?type=image&owner=me&status=active等复合条件无需新增端点； -
降低控制器职责耦合：
UserController专注用户生命周期操作（注册、登录、资料更新），不越界管理媒体逻辑； -
便于统一鉴权与审计：可在
MediaController全局拦截器中统一校验“当前用户是否有权访问其 own 媒体”，避免权限逻辑分散； -
兼容 OpenAPI/Swagger 文档生成：单个
GET /medias接口通过@Parameter注解即可清晰描述所有过滤能力，文档简洁专业。
⚠️ 不推荐方案辨析
-
/users/me/medias：虽语义直观（“我的媒体”属于“我”），但违反了“一个资源一个主路径”的核心约定。它将媒体资源从属关系强绑定到用户路径下，导致媒体无法被独立发现、缓存或跨上下文复用（例如管理员需查某用户媒体时，本应走/users/{id}/medias，而非复用/users/me/medias的逻辑）。 -
/medias/me：路径层级模糊——me并非媒体 ID，而是特殊标识符，易与真实资源 ID 冲突（如存在 ID 为"me"的媒体）；且难以扩展（/medias/me/favorites？/medias/me/archived？），最终仍会退化为参数化设计。
? 补充最佳实践
-
身份上下文提取：使用 Spring Security 的
SecurityContextHolder.getContext().getAuthentication()获取当前用户，避免在每个方法中重复解析 Token； -
参数标准化：建议统一使用
owner=me（而非userId=me或scope=my），语义明确且易于国际化； -
响应一致性：无论是否带
owner=me，返回结构保持一致（如Page<media></media>），前端无需条件分支处理； -
性能提示：对高频查询字段（如
owner_id）建立数据库索引，并考虑添加@Cacheable(key="#p0")缓存“我的媒体”结果（注意缓存失效策略）。
综上，/medias?owner=me 不仅是更“标准”的选择，更是面向演进的务实设计——它让 API 在功能增长时保持优雅，而非在路径爆炸中走向混乱。
