05-API设计-api-users到api-alerts的二十个接口黒漂技术佬 · AI 伙伴AI-Partner「数据接口部署与二次开发」系列 05数据层拆完了这篇上到接口层。AI 伙伴后端一共 9 个 Controller、19 个 HTTP 接口全部基于http://localhost:8080暴露。这篇逐个列出来讲清楚前缀划分的思路、根路径 HomeController 的用意以及接口版本化这个它没做、但你应该做的事。一、九个控制器总览Controller路由前缀接口数职责UserController/api/users1用户查找/注册ChatController/api/chat1陪伴对话核心接口ReminderController/api/reminders3提醒增/查/取消EmotionController/api/emotions2情绪记录/查询HealthController/api/health2健康记录/趋势DeviceController/api/devices4设备注册/绑定/列表/控制VisionController/api/vision2图片检测/跌倒检测AlertController/api/alerts2告警查询/状态流转HomeController无前缀2首页元信息/健康检查前缀划分遵循的是资源域一个业务域一个前缀域内再分动作。写代码找接口时按域定位看日志时按前缀归类一目了然。二、逐控制器接口清单2.1 用户与对话HTTP路径参数返回作用POST/api/usersBodyopenId必填、platform默认 web、nicknameApiResponseUser按openId查找或创建用户登录即注册POST/api/chatBodyuserId必填、message必填、sessionType默认 text、needTts默认 falseApiResponseChatResult发起一轮陪伴对话返回回复文本、audioUrl、耗时、conversationId/api/chat是全项目的中枢一次调用会触发调大模型 → 工具副作用落库 → 对话存档 → 可选 TTS的完整链路。2.2 提醒HTTP路径参数返回作用POST/api/remindersBodyuserId必填、title必填、content、remindTime、type默认 custom、cron、deviceIdApiResponseReminder创建提醒GET/api/remindersQueryuserIdApiResponseListReminder列出待触发提醒DELETE/api/reminders/{id}PathidQueryuserIdApiResponseString取消提醒注意 DELETE 还要传userId做归属校验——不是任何人都能取消任何人的提醒这是无鉴权体系下最朴素的权限防线。2.3 情绪与健康HTTP路径参数返回作用POST/api/emotionsBodyuserId必填、emotion必填、intensity默认 5、context、source默认 manualApiResponseEmotionRecord记录一条情绪GET/api/emotionsQueryuserIdApiResponseListEmotionRecord最近 10 条情绪POST/api/healthBodyuserId必填、type必填、value、unit、note、deviceIdApiResponseHealthRecord记录健康数据异常自动建告警工单GET/api/healthQueryuserId、typeApiResponseListHealthRecord近 7 天某类健康数据趋势2.4 设备HTTP路径参数返回作用POST/api/devices/registerQuerydeviceCode必填、name、type均可选ApiResponseDevice注册/认领设备已存在则返回原设备POST/api/devices/bindQueryuserId、deviceCodeApiResponseDevice用户绑定设备GET/api/devicesQueryuserIdApiResponseListDevice用户设备列表POST/api/devices/controlQueryuserId、deviceCode、action必填param可选ApiResponseString下发动作speak/gesture/light/wake/sleep设备这组接口全是 Query 参数而不是 JSON Body风格上和前几组不统一——能用但二次开发时建议统一成 Body 传参DTO 校验才用得上。2.5 视觉与告警HTTP路径参数返回作用POST/api/vision/detectmultipartfile图片、task默认 face可选 face/pose/fallApiResponseListDetection通用目标/姿态/跌倒检测POST/api/vision/fallmultipartfile图片ApiResponseBoolean是否检测到跌倒置信度阈值 0.6GET/api/alertsQueryuserId可选、status可选ApiResponseListAlert传 userId 按用户查默认 open不传查全部待处理PUT/api/alerts/{id}/statusPathidQuerystatusApiResponseAlert工单状态流转 open→processing/closed视觉接口内部会把图片转发给独立的 Python 视觉服务默认地址http://127.0.0.1:8000读取失败统一包装为BusinessException(图片读取失败…)。2.6 HomeController根路径的两张名片HTTP路径返回作用GET/ApiResponseMap服务元信息service/desc/docsGET/api/pingApiResponseString健康检查返回pong为什么HomeController放在根路径而不是塞进/api下因为它的服务对象不是业务前端而是人和运维工具浏览器地址栏敲个根路径就能看到这是什么服务部署脚本、探活检查用curl http://localhost:8080/api/ping验证服务是否活着。它游离于业务前缀之外是对外名片不是业务资源。这和 Spring Boot Actuator 的/actuator/health本项目也开了形成双保险ping 验应用进程actuator 验运行时状态。三、和标准 RESTful 的距离严格 RESTful 有一套名词资源 动词靠 HTTP 方法的教条。对照下来AI 伙伴是资源域 实用主义的混合体接口RESTful 教条写法实际写法点评注册设备POST /api/devicesPOST /api/devices/register动作后缀风格偏离但不影响理解绑定设备PUT /api/devices/{code}/ownerPOST /api/devices/bind同上更新工单状态PATCH /api/alerts/{id}PUT /api/alerts/{id}/status用子资源表达状态变更常见折中对话POST /api/conversationsPOST /api/chat动作语义优先聊天场景业界通行我的看法RESTful 是手段不是信仰。这个项目的接口在可预测、好调试、和前端沟通成本低这三件事上达标了个别不纯的地方register/bind 的动词后缀属于务实取舍。二次开发时保持两个底线即可前缀按资源域划、同域内风格统一。四、接口版本化的缺失与改进所有接口都直接挂在/api/**下没有/api/v1。当前单人开发问题不大但一旦外部小程序、H5 开始依赖你的接口改个字段就是线上事故。改进方案很轻路径版本/api/v1/users——最直观Nginx 路由也好配推荐Header 版本X-Api-Version: 1——路径干净但调试麻烦。落地成本几乎为零给 Controller 的RequestMapping统一加上 v1 前缀即可新版本来了再开/api/v2老版本并行一段时间后下线。五、完整的接口地图最后把 19 个接口拼成一张速查地图二次开发时对着查http://localhost:8080 ├─ GET / 服务元信息 ├─ GET /api/ping 健康检查 ├─ POST /api/users 查找或创建用户 ├─ POST /api/chat 陪伴对话 ├─ POST /api/reminders 创建提醒 ├─ GET /api/reminders 待触发提醒列表 ├─ DEL /api/reminders/{id} 取消提醒 ├─ POST /api/emotions 记录情绪 ├─ GET /api/emotions 最近10条情绪 ├─ POST /api/health 记录健康数据 ├─ GET /api/health 近7天健康趋势 ├─ POST /api/devices/register 注册设备 ├─ POST /api/devices/bind 绑定设备 ├─ GET /api/devices 用户设备列表 ├─ POST /api/devices/control 下发设备动作 ├─ POST /api/vision/detect 图片检测face/pose/fall ├─ POST /api/vision/fall 跌倒检测 ├─ GET /api/alerts 告警工单列表 └─ PUT /api/alerts/{id}/status 更新工单状态六、合规与安全提醒这份接口地图同时暴露了它的软肋没有任何鉴权未发现登录拦截器userId全靠客户端自报。对接任何真实用户前请至少做到三件事加一层认证JWT 或平台登录态校验把谁在调用变成服务端可信信息接口限频防止/api/chat被刷爆大模型账单健康与情绪接口必须做数据归属校验和授权管控——老人孩子的心率、情绪不该是任何拿到 userId 的人都能查的公开数据。小结9 个控制器、19 个接口按资源域划分前缀实用主义路线配上根路径的两张运维名片整体是一套教科书级的中小型项目接口组织。短板也很诚实没版本化、没鉴权——这正好是二次开发者练手的两个最佳切入点。下一篇我们看这些接口统一返回的ApiResponse三段式和全局异常处理。