小蓝书 Go
开发与源码

HTTP 接口手册

前置: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 不属于此公共契约。

— 本篇阅读完毕 —
来源:小蓝书 Go / docs / 03-development/api.md 下载原文
输入关键词,在三个知识库中搜索
支持正文检索 · 直接定位章节Esc 关闭