# HTTP 接口手册

前置：[Web 基础](../01-beginner/03-web-basics.md)、[认证边界](../02-architecture/security.md)。服务默认 `http://127.0.0.1:8080`，本章地址均以 `/api` 开头。除特殊标明外使用 POST + application/json。

## 统一规则

成功响应：`{"success":true,"data":...}`；失败响应：`{"success":false,"data":null,"message":"说明","errorCode":"APP-400"}`，同时使用正确 HTTP 状态码。业务数据可能为 null、字符串、对象或分页。

| 状态 | 含义 | 典型例子 |
| --- | --- | --- |
| 400 | 参数/业务前提错误 | 空标题、无效验证码、自关注 |
| 401 | 身份缺失或会话失效 | 未登录点赞、使用已退出的 token |
| 403 | 有身份但无此权限 | 修改他人笔记、普通用户访问后台 |
| 404 | 不存在或当前不可见 | 私密笔记、已删除评论 |
| 409 | 唯一值冲突 | 修改为已被使用的小蓝书号 |
| 429 | 发送或请求频率超限 | 一分钟内重复要验证码 |
| 500 / 502 | 内部错误 / 短信上游失败 | 数据库异常 / webhook 非成功 |

登录返回 token 字符串。后续请求头：`Authorization: Bearer <token>`。所有 ID 是 JavaScript 安全整数，客户端不得使用浮点或大于 `9007199254740991` 的 ID。分页固定每页 20 条，pageNo 从 1 开始，过小规范为 1，超过 10000 按 10000；totalPage 为 0 表示没有记录。

```json
{"success":true,"data":{"data":[],"pageNo":1,"totalCount":0,"pageSize":20,"totalPage":0}}
```

## 认证

| 地址 | 请求 | 身份与返回 |
| --- | --- | --- |
| `/api/auth/verification/code/send` | `{phone:"13800000001"}` | 不需登录；开发返回 `{message,debugCode}`，生产只有 message |
| `/api/auth/login` | `{phone,code,type:1}` 或 `{phone,password,type:2}` | 不需登录；返回 token；验证码首次登录自动注册 |
| `/api/auth/admin/login` | `{username,password}` | 不需登录；返回管理员 token |
| `/api/auth/logout` | `{}` | 需登录；撤销当前 session，返回 null |
| `/api/auth/password/update` | `{newPassword}` | 需登录；8～72字节，撤销其他设备会话，当前保留 |

验证码 5 分钟有效，每号码 60 秒间隔，最多 5 次错误，成功后不可重放。登录入口不解析请求头中的旧 token，允许失效会话重新认证。

完整 PowerShell 示例（开发环境）：

```powershell
$base='http://127.0.0.1:8080'
$codeResult=Invoke-RestMethod -Method Post -Uri "$base/api/auth/verification/code/send" -ContentType 'application/json' -Body '{"phone":"13800000001"}'
$loginBody=@{phone='13800000001';code=$codeResult.data.debugCode;type=1}|ConvertTo-Json
$login=Invoke-RestMethod -Method Post -Uri "$base/api/auth/login" -ContentType 'application/json' -Body $loginBody
$headers=@{Authorization='Bearer '+$login.data}
Invoke-RestMethod -Method Post -Uri "$base/api/user/user/profile" -Headers $headers -ContentType 'application/json' -Body '{}'
```

## 用户资料

`POST /api/user/user/profile` 请求 `{userId?}`。省略 userId 时需要登录，读取当前身份；明确传 ID 时可匿名读正常用户公开资料。返回 userId、avatar、nickname、xiaolanshuId、sex、birthday、introduction、followingTotal、fansTotal、noteTotal、likeTotal、collectTotal、likeAndCollectTotal、isFollowing。

`POST /api/user/user/update` 使用 multipart/form-data，字段 nickname、xiaolanshuId、introduction、sex、birthday，以及可选 avatar 文件。nickname 1～32字；handle 3～32位英文字母/数字/下划线/短横线；简介最多300字；birthday 为空或合法 YYYY-MM-DD（1900年至今天）；sex 0/1/2。始终修改当前用户，表单 userId 被忽略。成功返回新 Profile。

## 笔记

| 地址后缀（前缀 `/api/note/note`） | 请求 | 规则与返回 |
| --- | --- | --- |
| `/publish` | `{type,title,content,imgUris,videoUri?,topicId?}` | 登录；返回真实完整 Note |
| `/update` | publish 字段加 `{id}` | 仅作者；返回修改后的 Note |
| `/detail` | `{id}` | 可匿名读公开；私密仅作者；返回 Note |
| `/delete` | `{id}` | 仅作者；软删 |
| `/visible/onlyme` | `{id}` | 仅作者；visible=1 |
| `/visible/public` | `{id}` | 仅作者；visible=0 |
| `/top` | `{id,isTop:true/false}` | 仅作者；个人页置顶 |
| `/like`、`/unlike` | `{id}` | 登录；幂等设置点赞关系 |
| `/collect`、`/uncollect` | `{id}` | 登录；幂等设置收藏关系 |
| `/isLikedAndCollectedData` | `{noteId}` | 遵守笔记可见性；返回 `{noteId,isLiked,isCollected}` |
| `/published/list` | `{userId,cursor?}` | 返回 `{notes,nextCursor?}`，一次20篇，按ID递减 |

type=0 图文，至少1张、最多9张；type=1 视频，必须有合法 videoUri；标题1～80字，正文1～10000字。媒体只接受 `/uploads/`、`/assets/` 或合法 HTTPS URL。topicId 是非负可选元数据，当前没有话题名称目录。images 的首张是 cover。Note 还包含作者资料、计数字符串、visible、isTop、isLiked、isCollected 和 updateTime。

游标请求不使用 pageNo：读到 nextCursor 才继续。置顶在已加载的个人页笔记中排序；数据库游标仍按 ID，避免更改置顶造成跨页重复。它不保证一个很早的置顶笔记在尚未加载该页时就出现。

## 评论

| 地址后缀（前缀 `/api/comment/comment`） | 请求 | 规则 |
| --- | --- | --- |
| `/publish` | `{noteId,content,imageUrl?,replyCommentId?}` | 登录；1～1000字；回复必须同篇，返回真实 Comment |
| `/list` | `{noteId,pageNo?}` | 一级评论分页；先检查笔记可读 |
| `/child/list` | `{parentCommentId,pageNo?}` | 根评论的回复分页；先检查所属笔记 |
| `/like`、`/unlike` | `{commentId}` | 登录；幂等点赞/取消 |
| `/delete` | `{commentId}` | 评论作者、笔记作者或管理员；根评论连同回复软删 |

Comment 包括 commentId、userId、avatar、nickname、content、imageUrl、createTime、likeTotal、childCommentTotal、replyUserName、replyUserId、isLiked。回复的 parent_id 始终指根评论，reply_id 保留真实被回复对象。列表默认按 ID 升序。

## 关注与粉丝

| 地址（前缀 `/api/relation/relation`） | 请求 | 规则 |
| --- | --- | --- |
| `/follow` | `{followUserId}` | 登录；禁止自关注/停用目标；重复不新增 |
| `/unfollow` | `{unfollowUserId}` | 登录；取消不存在关系仍成功 |
| `/following/list` | `{userId,pageNo?}` | 正常目标用户列表 |
| `/fans/list` | `{userId,pageNo?}` | 正常来源用户列表 |

关系列表使用统一分页，返回 userId、avatar、nickname、introduction、xiaolanshuId；SearchUsers 还提供 fansTotal、noteTotal。

## 搜索与发现

`POST /api/search/note`：

```json
{"keyword":"咖啡","pageNo":1,"sort":0,"publishTimeRange":2,"type":0}
```

| 字段 | 含义 |
| --- | --- |
| keyword | 最多100字；空字符串可用于发现页 |
| type | 省略不限，0图文、1视频 |
| sort | 0最新，1最多点赞，2最多评论，3最多收藏 |
| publishTimeRange | 省略/0不限，1一天、2一周、3半年（180天） |
| tab | recommended / latest / following；following 必须登录，只看关注作者 |

recommended 的空关键词默认按点赞关系数再按 ID；latest 按 ID；搜索为字面子串匹配，不返回可直接插入页面的高亮 HTML。所有结果过滤不可见、已删除和停用作者。

`POST /api/search/user` 请求 `{keyword,pageNo?}`，匹配 nickname/handle，返回普通正常用户分页。不存在关键词时返回空数组，仍为200。

## 文件上传

`POST /api/file/upload`：登录；multipart 字段名 `file`；返回 URL 字符串，例如 `/uploads/随机值.jpg`。文件本体最多20 MiB；头像专用字段最多5 MiB；白名单 JPEG/PNG/WebP/GIF/MP4，通过前512字节识别 MIME。用户提交的原文件名不用于落盘。GET 返回文件时带 nosniff。

当前文件 URL 公开，不是私密相册签名地址。没有返回绝对 origin，方便开发代理、反向代理和 Docker 同源部署。

## 管理员

| 地址 | 请求 | 返回 |
| --- | --- | --- |
| `POST /api/admin/admin/dashboard` | `{}` | 用户/笔记/评论/赞/收藏/关系统计，databaseAvailable，redisAvailable=false，storage |
| `POST /api/admin/admin/users?pageNo=1&keyword=蓝&status=0` | `{}` | 用户分页；status可省略，0正常、1黑名单、2已删除 |
| `POST /api/admin/admin/users/{userId}/blacklist` | `{blacklisted:true/false}` | 更新状态并记审计；停用同时撤销全部会话 |
| `DELETE /api/admin/admin/users/{userId}` | 不需要 body | 软删除、撤销会话、记审计 |
| `POST /api/admin/admin/maintenance/check` | `{}` | integrity、foreignKeyViolations、搜索/计数策略说明 |

后台用户列表不包含管理员本身。完整性检查执行真实 PRAGMA，不伪造 Redis/ES 健康状态。所有管理端点都验证 Actor.Admin，不信任前端显示状态。

## 健康与静态资源

`GET /health/live`、`GET /health/ready` 当前都检查数据库 Ping；失败503。GET `/` 返回构建后的 SPA，GET `/assets/...` 静态资源，GET `/uploads/...` 用户文件。未知 `/api/...` 返回 JSON404，不返回 index.html；未构建前端时根页面明确503提示构建。

旧网关与服务前缀别名仅用于迁移兼容，见[迁移文档](../02-architecture/migration.md)。Java 内部 RPC 不属于此公共契约。
