[Refactor] 统一 Apollo-portal API 设计规范

[tacklequestions]

背景

当前Portal API 设计存在一些不规范和不一致的问题：

• RESTful 不规范：URL 中包含动词（如 /find-all-config），违背资源导向原则
• HTTP 方法模糊：部分接口用 @RequestMapping，未明确 GET/POST/PUT/DELETE
• 参数注解不一致：同一功能的参数，有的用 @RequestBody，有的用 @RequestParam
• 返回值混乱：有的返回 void，有的返回 ResponseEntity，部分直接返回数据库实体或 Spring Health 对象
• 分页参数校验不统一：有些接口用了 @Valid 验证，有些完全没验证
• 鉴权提示不细化：权限不足时只返回 403，缺少详细错误信息

---

改造目标

1. 统一 RESTful 风格：URL 资源化，明确 HTTP 方法
2. 统一参数与返回值：参数使用 DTO 封装，返回统一响应对象
3. 提升安全性：避免直接暴露数据库 PO 和内部健康检查信息
4. 统一分页与验证：所有分页接口使用统一的参数校验机制
5. 改进鉴权提示：提供详细错误码和缺失权限信息

---

技术方案

1. RESTful 设计

• URL 使用资源导向，如 /server/portal-db/configs
• 明确 HTTP 方法：GET / POST / PUT / DELETE

2. 参数与返回值

• 使用 DTO 封装参数，避免混用 @RequestParam 和 @RequestBody
• 响应统一使用 ResponseEntity<ApiResponse<T>>
• 引入 DTO 层，禁止直接返回 PO 实体
• 健康检查接口封装为 ServiceHealthResponse

3. 分页与校验

• 定义统一的 PageRequest DTO 或注解 @ValidPage / @ValidSize
• 所有分页接口保持一致性

4. 鉴权与错误提示

• 新增统一异常处理器 PermissionExceptionHandler
• 鉴权失败返回结构化错误：PERMISSION_DENIED、缺失权限、请求路径

---

预期收益

• 一致性：API 风格统一，易于前后端协作
• 安全性：避免敏感信息泄露
• 可维护性：统一的 DTO、统一的错误处理
• 开发体验：错误提示更清晰，便于排查问题

---

Checklist

• 修改 URL，移除动词，统一 RESTful 风格
• 明确所有接口的 HTTP 方法
• 使用 DTO 封装参数，统一请求方式
• 统一返回值格式，封装为 XxxResponse<T>
• 分页参数使用统一校验注解或 DTO
• 健康检查接口改为封装对象
• 实现统一的权限异常处理器

---