前置:Web 基础、认证边界。服务默认 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 表示没有记录。
{"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 示例(开发环境):
$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:
{"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提示构建。
旧网关与服务前缀别名仅用于迁移兼容,见迁移文档。Java 内部 RPC 不属于此公共契约。