清吾的 API
接口参考
一套用 Spring Boot 3 与 MySQL 构建的 RESTful 服务。统一的响应结构、语义化的状态码，以及与代码同步演进的接口契约。
1
curl -X POST https://boot.qingwu.ink/api/v1/auth/login -H "Content-Type: application/json" -d '{"username":"<你的账号>","password":"<你的密码>"}'
2
curl https://boot.qingwu.ink/api/v1/users/me -H "Authorization: Bearer <accessToken>"
3
https://boot.qingwu.ink/debug.html
打开可视化调试台，直接点击验证
模块总览
注册和登录5 个接口
签发与刷新访问令牌。除注册、登录与探测接口外，全部接口都要求携带令牌。
个人信息11 个接口当前登录用户的资料、密码、头像，以及收藏与评论的查看和管理。
用户管理5 个接口面向管理员的用户检索与治理能力，包括启禁用、角色调整与删除。
省市区11 个接口全国省、市、区县三级行政区划数据，支持级联查询、树形展开、拼音搜索与路径回溯。
新闻接口10 个接口新闻的分页检索、详情浏览、点赞与评论，供前台资讯流使用。
资讯管理5 个接口新闻内容的全生命周期管理：创建、编辑、上下架与删除。
新闻分类6 个接口资讯的顶层归类。分类下仍有新闻时不允许删除，避免出现游离内容。
天气预报5 个接口按城市查询今日实况与未来预报。数据为确定性生成的模拟数据，接入真实气象源时调用方无需改动。
图片上传2 个接口上传与回收图片文件，返回可直接访问的 URL，可用于头像或新闻封面。
系统信息3 个接口健康检查、服务器时间与枚举字典，适合探活、时间校准与下拉选项渲染。
操作日志2 个接口对写操作自动留痕的审计记录，包含操作人、耗时、请求参数与执行结果。
OpenAPI 规格JSON机器可读的完整契约，可直接导入 Postman、Apifox 或用于生成客户端 SDK。
基础约定
四个约定贯穿全部 65 个接口：统一的响应结构、语义化的状态码、Bearer 令牌鉴权，以及一致的参数校验反馈。
基础地址
所有接口统一挂载在 /api/v1 之下，版本号体现在路径中，便于未来平滑演进。
请求与响应
请求体统一为 application/json（文件上传为 multipart/form-data），响应统一为 JSON。
时间格式
日期时间使用 yyyy-MM-dd HH:mm:ss，日期使用 yyyy-MM-dd，时区固定为 Asia/Shanghai。
分页约定
页码从 1 开始。请求使用 pageNum 与 pageSize，pageSize 上限为 100。
统一响应结构 所有接口，含错误响应
无论成功还是失败，响应体始终包含 code、message、data 三个字段。
data 在无返回内容时为 null，字段本身不会消失。
成功响应
{
"code": 200,
"message": "操作成功",
"data": { "id": 1, "username": "admin" },
"timestamp": 1792113926072,
"success": true
}
错误响应（HTTP 401）
{
"code": 401,
"message": "未登录或登录已过期",
"data": null,
"timestamp": 1792113835714,
"success": false
}
鉴权与权限 Bearer 令牌 · 三级可见性
除标注为「公开」的接口外，全部接口都要求在请求头携带访问令牌。标注为「管理员」的接口还要求账号角色为 ADMIN。
请求头
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxIn0.SIGNATURE
公开 —— 无需令牌。若仍携带了合法令牌，服务端会解析出用户身份，用于返回
favorited 这类个性化字段。需登录 —— 缺少或令牌失效时返回
401。管理员 —— 已登录但角色不足时返回
403，错误码 1011。accessToken 有效期 2 小时，refreshToken 有效期 7 天，签名算法 HS256。
状态码 60 个码位，按业务域分区
code 与 HTTP 状态码语义保持一致。1xxx 起为业务细分码，按模块分区：用户 1xxx、地区 2xxx、资讯 3xxx、天气 4xxx、文件 5xxx。
通用
200 / 201
成功 / 创建成功
400
请求参数错误
401
未登录或登录已过期
403
无权限访问该资源
404
请求的资源不存在
405
请求方法不被支持
409
数据冲突
413
上传内容超过大小限制
500 / 503
服务器内部错误 / 服务不可用
用户 1xxx
1001 · 1002 · 1003
用户名 / 邮箱 / 手机号已存在
1004
用户不存在
1005
用户名或密码错误
1006
账号已被禁用
1007
原密码不正确
1008
两次输入的密码不一致
1009
Token 无效
1010
Token 已过期
1011
该操作需要管理员权限
地区 2xxx · 资讯 3xxx
2001
地区不存在
2002
地区层级不正确
2003
该地区下存在子区域
3001
新闻不存在或已下架
3002
新闻分类不存在
3003
分类名称已存在
3004
该分类下仍有新闻
3005 / 3006
重复收藏 / 尚未收藏
天气 4xxx · 文件 5xxx
4001
暂无该城市的天气数据
4002
请指定城市名称或城市 ID
5001
上传文件不能为空
5002
不支持的文件类型
5003
文件上传失败
参数校验 字段级错误定位
参数校验在控制器层完成。校验失败返回 400，message 中会聚合全部失败字段，格式为 字段名: 提示语，多个字段以分号分隔。
校验失败响应
{
"code": 400,
"message": "username: 用户名需为 4-20 位字母、数字或下划线",
"data": null,
"timestamp": 1792113926072,
"success": false
}
注册和登录
注册
创建新账号。密码以 BCrypt 加盐哈希后落库，任何接口都不会返回密码字段。
接口概要
鉴权要求
公开（无需令牌）
请求内容类型
application/json
响应内容类型
application/json
幂等性
非幂等，重复提交会产生多条数据
响应数据模型
UserVO
所属模块
注册和登录
请求体字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| username | string | 必填 | 用户名：4-20 位字母、数字或下划线 例如 zhangsan |
| password | string | 必填 | 密码：6-20 位 例如 123456 |
| confirmPassword | string | 必填 | 确认密码 例如 123456 |
| nickname | string | 可选 | 昵称 例如 张三 |
| string | 可选 | 邮箱 例如 zhangsan@example.com | |
| phone | string | 可选 | 手机号 例如 13800000001 |
| provinceId | integer | 可选 | 省份 ID 例如 440000 |
| cityId | integer | 可选 | 城市 ID 例如 440100 |
| districtId | integer | 可选 | 区县 ID 例如 440106 |
请求示例7 种语言
该接口无需令牌，可直接调用。把示例中的参数值换成你的实际值即可。
curl -X POST 'https://boot.qingwu.ink/api/v1/auth/register'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-d '{
"username": "zhangsan",
"password": "123456",
"confirmPassword": "123456",
"nickname": "张三",
"email": "zhangsan@example.com",
"phone": "13800000001"
}'const res = await fetch('https://boot.qingwu.ink/api/v1/auth/register', {
method: 'POST',
headers: {
'Accept': 'application/json',
'Content-Type': 'application/json',
},
body: JSON.stringify(payload),
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.post(
"https://boot.qingwu.ink/api/v1/auth/register",
headers={
"Accept": "application/json",
"Content-Type": "application/json",
},
json=payload,
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/auth/register"))
.header("Accept", "application/json")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(body))
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("POST", "https://boot.qingwu.ink/api/v1/auth/register", strings.NewReader(body))
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/auth/register");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => $body,
]);
echo curl_exec($ch);
curl_close($ch);POST /api/v1/auth/register HTTP/1.1
Host: boot.qingwu.ink
Accept: application/json
Content-Type: application/json
{
"username": "zhangsan",
"password": "123456",
"confirmPassword": "123456",
"nickname": "张三",
"email": "zhangsan@example.com",
"phone": "13800000001"
}响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": {
"id": 1,
"username": "admin",
"nickname": "系统管理员",
"email": "admin@example.com",
"phone": "13800000000",
"avatar": null,
"gender": 1,
"birthday": null,
"provinceId": 110000,
"provinceName": "北京市",
"cityId": 110100,
"cityName": "市辖区",
"districtId": 110105,
"districtName": "朝阳区",
"signature": "保持简洁",
"role": "ADMIN",
"status": 1,
"lastLoginTime": "2026-10-16 09:23:12",
"createTime": "2026-10-16 08:59:41"
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 UserVO
| 字段 | 类型 | 说明 |
|---|---|---|
| id | integer | 用户 ID 例如 1 |
| username | string | 用户名 例如 admin |
| nickname | string | 昵称 例如 系统管理员 |
| string | 邮箱 例如 admin@example.com | |
| phone | string | 手机号 例如 13800000000 |
| avatar | string | 头像 URL |
| gender | integer | 性别：0-未知 1-男 2-女 例如 1 |
| birthday | string | 生日 |
| provinceId | integer | 省份 ID 例如 110000 |
| provinceName | string | 省份名称 例如 北京市 |
| cityId | integer | 城市 ID 例如 110100 |
| cityName | string | 城市名称 例如 市辖区 |
| districtId | integer | 区县 ID 例如 110105 |
| districtName | string | 区县名称 例如 朝阳区 |
| address | string | 详细地址 |
| signature | string | 个性签名 |
| role | string | 角色 例如 ADMIN |
| status | integer | 状态：1-正常 0-禁用 例如 1 |
| lastLoginTime | string | 最近登录时间 |
| createTime | string | 注册时间 |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 201 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 409 | 用户名、邮箱或手机号已被占用 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 1001 | 用户名已被注册 |
| 1002 | 邮箱已被注册 |
| 1003 | 手机号已被注册 |
| 1008 | 两次输入的密码不一致 |
说明
成功时返回 HTTP 201，
code 同步为 201，与普通成功响应区分。用户名需为 4–20 位字母、数字或下划线；密码 6–20 位。两次密码不一致返回
1008。注册和登录
登录
校验账号密码并签发令牌。用户名不存在与密码错误返回同一提示，避免账号被枚举。
接口概要
鉴权要求
公开（无需令牌）
请求内容类型
application/json
响应内容类型
application/json
幂等性
非幂等，重复提交会产生多条数据
响应数据模型
LoginVO
所属模块
注册和登录
请求体字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| username | string | 必填 | 用户名 例如 admin |
| password | string | 必填 | 密码 例如 admin123 |
请求示例7 种语言
该接口无需令牌，可直接调用。把示例中的参数值换成你的实际值即可。
curl -X POST 'https://boot.qingwu.ink/api/v1/auth/login'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-d '{
"username": "admin",
"password": "admin123"
}'const res = await fetch('https://boot.qingwu.ink/api/v1/auth/login', {
method: 'POST',
headers: {
'Accept': 'application/json',
'Content-Type': 'application/json',
},
body: JSON.stringify(payload),
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.post(
"https://boot.qingwu.ink/api/v1/auth/login",
headers={
"Accept": "application/json",
"Content-Type": "application/json",
},
json=payload,
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/auth/login"))
.header("Accept", "application/json")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(body))
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("POST", "https://boot.qingwu.ink/api/v1/auth/login", strings.NewReader(body))
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/auth/login");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => $body,
]);
echo curl_exec($ch);
curl_close($ch);POST /api/v1/auth/login HTTP/1.1
Host: boot.qingwu.ink
Accept: application/json
Content-Type: application/json
{
"username": "admin",
"password": "admin123"
}响应示例
200 OK
{
"code": 200,
"message": "登录成功",
"data": {
"accessToken": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiJ9.SIGNATURE",
"refreshToken": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxIiwidHlwZSI6InJlZnJlc2gifQ.SIGNATURE",
"tokenType": "Bearer",
"expiresIn": 7200,
"user": {
"id": 1,
"username": "admin",
"nickname": "系统管理员",
"email": "admin@example.com",
"phone": "13800000000",
"avatar": null,
"gender": 1,
"birthday": null,
"provinceId": 110000,
"provinceName": "北京市",
"cityId": 110100,
"cityName": "市辖区",
"districtId": 110105,
"districtName": "朝阳区",
"signature": "保持简洁",
"role": "ADMIN",
"status": 1,
"lastLoginTime": "2026-10-16 09:23:12",
"createTime": "2026-10-16 08:59:41"
}
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 LoginVO
| 字段 | 类型 | 说明 |
|---|---|---|
| accessToken | string | 访问令牌，后续请求放入 Authorization 请求头 |
| refreshToken | string | 刷新令牌，用于换取新的 accessToken |
| tokenType | string | 令牌类型 例如 Bearer |
| expiresIn | integer | accessToken 有效期（秒） 例如 7200 |
| user | UserVO | — |
| user.id | integer | 用户 ID 例如 1 |
| user.username | string | 用户名 例如 admin |
| user.nickname | string | 昵称 例如 系统管理员 |
| user.email | string | 邮箱 例如 admin@example.com |
| user.phone | string | 手机号 例如 13800000000 |
| user.avatar | string | 头像 URL |
| user.gender | integer | 性别：0-未知 1-男 2-女 例如 1 |
| user.birthday | string | 生日 |
| user.provinceId | integer | 省份 ID 例如 110000 |
| user.provinceName | string | 省份名称 例如 北京市 |
| user.cityId | integer | 城市 ID 例如 110100 |
| user.cityName | string | 城市名称 例如 市辖区 |
| user.districtId | integer | 区县 ID 例如 110105 |
| user.districtName | string | 区县名称 例如 朝阳区 |
| user.address | string | 详细地址 |
| user.signature | string | 个性签名 |
| user.role | string | 角色 例如 ADMIN |
| user.status | integer | 状态：1-正常 0-禁用 例如 1 |
| user.lastLoginTime | string | 最近登录时间 |
| user.createTime | string | 注册时间 |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 1005 | 用户名或密码错误 |
| 1006 | 账号已被禁用，请联系管理员 |
说明
账号被禁用时返回
1006，不会签发令牌。登录成功会同时更新
lastLoginTime 与 lastLoginIp。注册和登录
刷新令牌
用尚未过期的 refreshToken 换取一对新令牌，适用于 accessToken 即将到期时静默续期。
接口概要
鉴权要求
公开（无需令牌）
请求内容类型
application/json
响应内容类型
application/json
幂等性
非幂等，重复提交会产生多条数据
响应数据模型
LoginVO
所属模块
注册和登录
请求体字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| refreshToken | string | 必填 | — |
请求示例7 种语言
该接口无需令牌，可直接调用。把示例中的参数值换成你的实际值即可。
curl -X POST 'https://boot.qingwu.ink/api/v1/auth/refresh'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-d '{
"refreshToken": "eyJhbGciOiJIUzI1NiJ9...SIGNATURE"
}'const res = await fetch('https://boot.qingwu.ink/api/v1/auth/refresh', {
method: 'POST',
headers: {
'Accept': 'application/json',
'Content-Type': 'application/json',
},
body: JSON.stringify(payload),
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.post(
"https://boot.qingwu.ink/api/v1/auth/refresh",
headers={
"Accept": "application/json",
"Content-Type": "application/json",
},
json=payload,
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/auth/refresh"))
.header("Accept", "application/json")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(body))
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("POST", "https://boot.qingwu.ink/api/v1/auth/refresh", strings.NewReader(body))
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/auth/refresh");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => $body,
]);
echo curl_exec($ch);
curl_close($ch);POST /api/v1/auth/refresh HTTP/1.1
Host: boot.qingwu.ink
Accept: application/json
Content-Type: application/json
{
"refreshToken": "eyJhbGciOiJIUzI1NiJ9...SIGNATURE"
}响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": {
"accessToken": "eyJhbGciOiJIUzI1NiJ9...NEW",
"refreshToken": "eyJhbGciOiJIUzI1NiJ9...NEW",
"tokenType": "Bearer",
"expiresIn": 7200,
"user": {
"id": 1,
"username": "admin",
"nickname": "系统管理员",
"email": "admin@example.com",
"phone": "13800000000",
"avatar": null,
"gender": 1,
"birthday": null,
"provinceId": 110000,
"provinceName": "北京市",
"cityId": 110100,
"cityName": "市辖区",
"districtId": 110105,
"districtName": "朝阳区",
"signature": "保持简洁",
"role": "ADMIN",
"status": 1,
"lastLoginTime": "2026-10-16 09:23:12",
"createTime": "2026-10-16 08:59:41"
}
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 LoginVO
| 字段 | 类型 | 说明 |
|---|---|---|
| accessToken | string | 访问令牌，后续请求放入 Authorization 请求头 |
| refreshToken | string | 刷新令牌，用于换取新的 accessToken |
| tokenType | string | 令牌类型 例如 Bearer |
| expiresIn | integer | accessToken 有效期（秒） 例如 7200 |
| user | UserVO | — |
| user.id | integer | 用户 ID 例如 1 |
| user.username | string | 用户名 例如 admin |
| user.nickname | string | 昵称 例如 系统管理员 |
| user.email | string | 邮箱 例如 admin@example.com |
| user.phone | string | 手机号 例如 13800000000 |
| user.avatar | string | 头像 URL |
| user.gender | integer | 性别：0-未知 1-男 2-女 例如 1 |
| user.birthday | string | 生日 |
| user.provinceId | integer | 省份 ID 例如 110000 |
| user.provinceName | string | 省份名称 例如 北京市 |
| user.cityId | integer | 城市 ID 例如 110100 |
| user.cityName | string | 城市名称 例如 市辖区 |
| user.districtId | integer | 区县 ID 例如 110105 |
| user.districtName | string | 区县名称 例如 朝阳区 |
| user.address | string | 详细地址 |
| user.signature | string | 个性签名 |
| user.role | string | 角色 例如 ADMIN |
| user.status | integer | 状态：1-正常 0-禁用 例如 1 |
| user.lastLoginTime | string | 最近登录时间 |
| user.createTime | string | 注册时间 |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 1009 | Token 无效 |
| 1010 | Token 已过期，请重新登录 |
说明
传入 accessToken 会被拒绝并返回
1009，此接口只接受 refreshToken。注册和登录
退出登录
服务端不维护会话状态，此接口供客户端统一调用；清除本地令牌即完成登出。
接口概要
鉴权要求
需登录（缺少有效令牌返回 401）
请求内容类型
—
响应内容类型
application/json
幂等性
非幂等，重复提交会产生多条数据
响应数据模型
基本类型 / 空值
所属模块
注册和登录
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X POST 'https://boot.qingwu.ink/api/v1/auth/logout' -H 'Accept: application/json' -H 'Authorization: Bearer <accessToken>'
const res = await fetch('https://boot.qingwu.ink/api/v1/auth/logout', {
method: 'POST',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`,
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.post(
"https://boot.qingwu.ink/api/v1/auth/logout",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {access_token}",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/auth/logout"))
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.POST()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("POST", "https://boot.qingwu.ink/api/v1/auth/logout", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer " + accessToken)
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/auth/logout");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Authorization: Bearer " . $accessToken,
],
]);
echo curl_exec($ch);
curl_close($ch);POST /api/v1/auth/logout HTTP/1.1 Host: boot.qingwu.ink Authorization: Bearer <accessToken> Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "已退出登录",
"data": null,
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明
该接口的 data 为基本类型或空值，没有可展开的字段。
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 1009 | Token 无效 |
| 1010 | Token 已过期，请重新登录 |
说明
如需「退出即失效 / 强制下线」，可在网关或服务端引入令牌黑名单。
注册和登录
连通性探测
最轻量的探活接口，不需要令牌，可用于登录页判断服务可达性。
接口概要
鉴权要求
公开（无需令牌）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
基本类型 / 空值
所属模块
注册和登录
请求示例7 种语言
该接口无需令牌，可直接调用。把示例中的参数值换成你的实际值即可。
curl -X GET 'https://boot.qingwu.ink/api/v1/auth/ping' -H 'Accept: application/json'
const res = await fetch('https://boot.qingwu.ink/api/v1/auth/ping', {
method: 'GET',
headers: {
'Accept': 'application/json',
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/auth/ping",
headers={
"Accept": "application/json",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/auth/ping"))
.header("Accept", "application/json")
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/auth/ping", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/auth/ping");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/auth/ping HTTP/1.1 Host: boot.qingwu.ink Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": "pong",
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明
该接口的 data 为基本类型或空值，没有可展开的字段。
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
说明
该接口为公开接口，无需任何凭证即可调用。
个人信息
当前用户
返回令牌所属用户的完整资料，含地区名称等派生字段。
接口概要
鉴权要求
需登录（缺少有效令牌返回 401）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
UserVO
所属模块
个人信息
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X GET 'https://boot.qingwu.ink/api/v1/users/me' -H 'Accept: application/json' -H 'Authorization: Bearer <accessToken>'
const res = await fetch('https://boot.qingwu.ink/api/v1/users/me', {
method: 'GET',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`,
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/users/me",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {access_token}",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/users/me"))
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/users/me", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer " + accessToken)
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/users/me");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Authorization: Bearer " . $accessToken,
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/users/me HTTP/1.1 Host: boot.qingwu.ink Authorization: Bearer <accessToken> Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": {
"id": 1,
"username": "admin",
"nickname": "系统管理员",
"email": "admin@example.com",
"phone": "13800000000",
"avatar": null,
"gender": 1,
"birthday": null,
"provinceId": 110000,
"provinceName": "北京市",
"cityId": 110100,
"cityName": "市辖区",
"districtId": 110105,
"districtName": "朝阳区",
"signature": "保持简洁",
"role": "ADMIN",
"status": 1,
"lastLoginTime": "2026-10-16 09:23:12",
"createTime": "2026-10-16 08:59:41"
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 UserVO
| 字段 | 类型 | 说明 |
|---|---|---|
| id | integer | 用户 ID 例如 1 |
| username | string | 用户名 例如 admin |
| nickname | string | 昵称 例如 系统管理员 |
| string | 邮箱 例如 admin@example.com | |
| phone | string | 手机号 例如 13800000000 |
| avatar | string | 头像 URL |
| gender | integer | 性别：0-未知 1-男 2-女 例如 1 |
| birthday | string | 生日 |
| provinceId | integer | 省份 ID 例如 110000 |
| provinceName | string | 省份名称 例如 北京市 |
| cityId | integer | 城市 ID 例如 110100 |
| cityName | string | 城市名称 例如 市辖区 |
| districtId | integer | 区县 ID 例如 110105 |
| districtName | string | 区县名称 例如 朝阳区 |
| address | string | 详细地址 |
| signature | string | 个性签名 |
| role | string | 角色 例如 ADMIN |
| status | integer | 状态：1-正常 0-禁用 例如 1 |
| lastLoginTime | string | 最近登录时间 |
| createTime | string | 注册时间 |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
说明
个人中心接口作用于当前令牌所属的用户，无需在路径中传用户 ID。
需在请求头携带
Authorization: Bearer ；令牌过期请先用刷新令牌接口换取新的访问令牌。个人信息
修改个人资料
按字段增量更新。只需提交要变更的字段，未提交的字段保持原值。
接口概要
鉴权要求
需登录（缺少有效令牌返回 401）
请求内容类型
application/json
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
UserVO
所属模块
个人信息
请求体字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| nickname | string | 可选 | 昵称 例如 张三 |
| string | 可选 | 邮箱 例如 zhangsan@example.com | |
| phone | string | 可选 | 手机号 例如 13800000001 |
| avatar | string | 可选 | 头像 URL |
| gender | integer | 可选 | 性别：0-未知 1-男 2-女 例如 1 |
| birthday | string | 可选 | 生日 例如 1995-06-01 |
| provinceId | integer | 可选 | 省份 ID 例如 440000 |
| cityId | integer | 可选 | 城市 ID 例如 440100 |
| districtId | integer | 可选 | 区县 ID 例如 440106 |
| address | string | 可选 | 详细地址 |
| signature | string | 可选 | 个性签名 |
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X PUT 'https://boot.qingwu.ink/api/v1/users/me'
-H 'Accept: application/json'
-H 'Authorization: Bearer <accessToken>'
-H 'Content-Type: application/json'
-d '{
"nickname": "张三",
"email": "zhangsan@example.com",
"gender": 1,
"birthday": "1995-06-01",
"provinceId": 440000,
"cityId": 440100,
"districtId": 440106,
"signature": "保持简洁"
}'const res = await fetch('https://boot.qingwu.ink/api/v1/users/me', {
method: 'PUT',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(payload),
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.put(
"https://boot.qingwu.ink/api/v1/users/me",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {access_token}",
"Content-Type": "application/json",
},
json=payload,
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/users/me"))
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.header("Content-Type", "application/json")
.PUT(HttpRequest.BodyPublishers.ofString(body))
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("PUT", "https://boot.qingwu.ink/api/v1/users/me", strings.NewReader(body))
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer " + accessToken)
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/users/me");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Authorization: Bearer " . $accessToken,
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => $body,
]);
echo curl_exec($ch);
curl_close($ch);PUT /api/v1/users/me HTTP/1.1
Host: boot.qingwu.ink
Authorization: Bearer <accessToken>
Accept: application/json
Content-Type: application/json
{
"nickname": "张三",
"email": "zhangsan@example.com",
"gender": 1,
"birthday": "1995-06-01",
"provinceId": 440000,
"cityId": 440100,
"districtId": 440106,
"signature": "保持简洁"
}响应示例
200 OK
{
"code": 200,
"message": "资料已更新",
"data": {
"id": 1,
"username": "admin",
"nickname": "系统管理员",
"email": "admin@example.com",
"phone": "13800000000",
"avatar": null,
"gender": 1,
"birthday": null,
"provinceId": 110000,
"provinceName": "北京市",
"cityId": 110100,
"cityName": "市辖区",
"districtId": 110105,
"districtName": "朝阳区",
"signature": "保持简洁",
"role": "ADMIN",
"status": 1,
"lastLoginTime": "2026-10-16 09:23:12",
"createTime": "2026-10-16 08:59:41"
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 UserVO
| 字段 | 类型 | 说明 |
|---|---|---|
| id | integer | 用户 ID 例如 1 |
| username | string | 用户名 例如 admin |
| nickname | string | 昵称 例如 系统管理员 |
| string | 邮箱 例如 admin@example.com | |
| phone | string | 手机号 例如 13800000000 |
| avatar | string | 头像 URL |
| gender | integer | 性别：0-未知 1-男 2-女 例如 1 |
| birthday | string | 生日 |
| provinceId | integer | 省份 ID 例如 110000 |
| provinceName | string | 省份名称 例如 北京市 |
| cityId | integer | 城市 ID 例如 110100 |
| cityName | string | 城市名称 例如 市辖区 |
| districtId | integer | 区县 ID 例如 110105 |
| districtName | string | 区县名称 例如 朝阳区 |
| address | string | 详细地址 |
| signature | string | 个性签名 |
| role | string | 角色 例如 ADMIN |
| status | integer | 状态：1-正常 0-禁用 例如 1 |
| lastLoginTime | string | 最近登录时间 |
| createTime | string | 注册时间 |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
说明
个人中心接口作用于当前令牌所属的用户，无需在路径中传用户 ID。
邮箱与手机号需全局唯一，冲突时分别返回
1002 / 1003。个人信息
修改头像
单独更新头像地址，通常传入文件上传接口返回的 URL。
接口概要
鉴权要求
需登录（缺少有效令牌返回 401）
请求内容类型
application/json
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
UserVO
所属模块
个人信息
请求体字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| avatar | string | 必填 | — |
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X PUT 'https://boot.qingwu.ink/api/v1/users/me/avatar'
-H 'Accept: application/json'
-H 'Authorization: Bearer <accessToken>'
-H 'Content-Type: application/json'
-d '{
"avatar": "/uploads/avatar/2026/10/16/9f3c1a2b7e.png"
}'const res = await fetch('https://boot.qingwu.ink/api/v1/users/me/avatar', {
method: 'PUT',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(payload),
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.put(
"https://boot.qingwu.ink/api/v1/users/me/avatar",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {access_token}",
"Content-Type": "application/json",
},
json=payload,
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/users/me/avatar"))
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.header("Content-Type", "application/json")
.PUT(HttpRequest.BodyPublishers.ofString(body))
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("PUT", "https://boot.qingwu.ink/api/v1/users/me/avatar", strings.NewReader(body))
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer " + accessToken)
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/users/me/avatar");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Authorization: Bearer " . $accessToken,
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => $body,
]);
echo curl_exec($ch);
curl_close($ch);PUT /api/v1/users/me/avatar HTTP/1.1
Host: boot.qingwu.ink
Authorization: Bearer <accessToken>
Accept: application/json
Content-Type: application/json
{
"avatar": "/uploads/avatar/2026/10/16/9f3c1a2b7e.png"
}响应示例
200 OK
{
"code": 200,
"message": "头像已更新",
"data": {
"id": 1,
"username": "admin",
"nickname": "系统管理员",
"email": "admin@example.com",
"phone": "13800000000",
"avatar": null,
"gender": 1,
"birthday": null,
"provinceId": 110000,
"provinceName": "北京市",
"cityId": 110100,
"cityName": "市辖区",
"districtId": 110105,
"districtName": "朝阳区",
"signature": "保持简洁",
"role": "ADMIN",
"status": 1,
"lastLoginTime": "2026-10-16 09:23:12",
"createTime": "2026-10-16 08:59:41"
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 UserVO
| 字段 | 类型 | 说明 |
|---|---|---|
| id | integer | 用户 ID 例如 1 |
| username | string | 用户名 例如 admin |
| nickname | string | 昵称 例如 系统管理员 |
| string | 邮箱 例如 admin@example.com | |
| phone | string | 手机号 例如 13800000000 |
| avatar | string | 头像 URL |
| gender | integer | 性别：0-未知 1-男 2-女 例如 1 |
| birthday | string | 生日 |
| provinceId | integer | 省份 ID 例如 110000 |
| provinceName | string | 省份名称 例如 北京市 |
| cityId | integer | 城市 ID 例如 110100 |
| cityName | string | 城市名称 例如 市辖区 |
| districtId | integer | 区县 ID 例如 110105 |
| districtName | string | 区县名称 例如 朝阳区 |
| address | string | 详细地址 |
| signature | string | 个性签名 |
| role | string | 角色 例如 ADMIN |
| status | integer | 状态：1-正常 0-禁用 例如 1 |
| lastLoginTime | string | 最近登录时间 |
| createTime | string | 注册时间 |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
说明
个人中心接口作用于当前令牌所属的用户，无需在路径中传用户 ID。
字段校验在进入业务逻辑之前完成，未通过时
message 会聚合全部字段的错误提示。需在请求头携带
Authorization: Bearer ；令牌过期请先用刷新令牌接口换取新的访问令牌。个人信息
修改密码
校验原密码后写入新的 BCrypt 哈希。新旧密码相同时会被拒绝。
接口概要
鉴权要求
需登录（缺少有效令牌返回 401）
请求内容类型
application/json
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
基本类型 / 空值
所属模块
个人信息
请求体字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| oldPassword | string | 必填 | 原密码 例如 123456 |
| newPassword | string | 必填 | 新密码：6-20 位 例如 abc123456 |
| confirmPassword | string | 必填 | 确认新密码 例如 abc123456 |
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X PUT 'https://boot.qingwu.ink/api/v1/users/me/password'
-H 'Accept: application/json'
-H 'Authorization: Bearer <accessToken>'
-H 'Content-Type: application/json'
-d '{
"oldPassword": "123456",
"newPassword": "abc123456",
"confirmPassword": "abc123456"
}'const res = await fetch('https://boot.qingwu.ink/api/v1/users/me/password', {
method: 'PUT',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(payload),
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.put(
"https://boot.qingwu.ink/api/v1/users/me/password",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {access_token}",
"Content-Type": "application/json",
},
json=payload,
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/users/me/password"))
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.header("Content-Type", "application/json")
.PUT(HttpRequest.BodyPublishers.ofString(body))
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("PUT", "https://boot.qingwu.ink/api/v1/users/me/password", strings.NewReader(body))
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer " + accessToken)
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/users/me/password");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Authorization: Bearer " . $accessToken,
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => $body,
]);
echo curl_exec($ch);
curl_close($ch);PUT /api/v1/users/me/password HTTP/1.1
Host: boot.qingwu.ink
Authorization: Bearer <accessToken>
Accept: application/json
Content-Type: application/json
{
"oldPassword": "123456",
"newPassword": "abc123456",
"confirmPassword": "abc123456"
}响应示例
200 OK
{
"code": 200,
"message": "密码修改成功",
"data": null,
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明
该接口的 data 为基本类型或空值，没有可展开的字段。
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 1005 | 用户名或密码错误 |
| 1007 | 原密码不正确 |
| 1008 | 两次输入的密码不一致 |
说明
个人中心接口作用于当前令牌所属的用户，无需在路径中传用户 ID。
原密码错误返回
1007；两次新密码不一致返回 1008。个人信息
我的收藏
分页返回当前用户收藏的新闻，按收藏时间倒序，结果中的 favorited 恒为 true。
接口概要
鉴权要求
需登录（缺少有效令牌返回 401）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
PageResult<NewsVO>
所属模块
个人信息
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| pageNum | integer | 可选 | 页码，从 1 开始 例如 1 |
| pageSize | integer | 可选 | 每页条数，最大 100 例如 10 |
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X GET 'https://boot.qingwu.ink/api/v1/users/me/favorites?pageNum=1&pageSize=10' -H 'Accept: application/json' -H 'Authorization: Bearer <accessToken>'
const res = await fetch('https://boot.qingwu.ink/api/v1/users/me/favorites?pageNum=1&pageSize=10', {
method: 'GET',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`,
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/users/me/favorites?pageNum=1&pageSize=10",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {access_token}",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/users/me/favorites?pageNum=1&pageSize=10"))
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/users/me/favorites?pageNum=1&pageSize=10", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer " + accessToken)
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/users/me/favorites?pageNum=1&pageSize=10");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Authorization: Bearer " . $accessToken,
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/users/me/favorites?pageNum=1&pageSize=10 HTTP/1.1 Host: boot.qingwu.ink Authorization: Bearer <accessToken> Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": {
"pageNum": 1,
"pageSize": 5,
"total": 12,
"pages": 3,
"list": [
{
"id": 4,
"title": "A 股三大指数集体收涨 成交额突破 1.2 万亿",
"summary": "市场情绪回暖，券商、新能源板块领涨，北向资金净流入超 60 亿元。",
"coverImage": null,
"author": "编辑部",
"source": "清吾资讯",
"categoryId": 2,
"categoryName": "财经金融",
"tags": [
"A股",
"股市"
],
"viewCount": 2155,
"likeCount": 143,
"commentCount": 0,
"isTop": 1,
"isHot": 1,
"status": 1,
"publishTime": "2026-10-16 08:54:41",
"favorited": false
}
]
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 PageResult<NewsVO>
| 字段 | 类型 | 说明 |
|---|---|---|
| pageNum | integer | 当前页码 |
| pageSize | integer | 每页条数 |
| total | integer | 记录总数 |
| pages | integer | 总页数 |
| list | array<NewsVO> | 当前页的数据集合 |
| list.id | integer | 新闻 ID 例如 1 |
| list.title | string | 标题 |
| list.summary | string | 摘要 |
| list.coverImage | string | 封面图 |
| list.author | string | 作者 |
| list.source | string | 来源 |
| list.categoryId | integer | 分类 ID 例如 3 |
| list.categoryName | string | 分类名称 例如 科技互联网 |
| list.tags | array<string> | 标签列表 |
| list.viewCount | integer | 浏览量 例如 1024 |
| list.likeCount | integer | 点赞数 例如 58 |
| list.commentCount | integer | 评论数 例如 12 |
| list.isTop | integer | 是否置顶：1-是 0-否 |
| list.isHot | integer | 是否热门：1-是 0-否 |
| list.status | integer | 状态：0-草稿 1-已发布 2-已下架 |
| list.publishTime | string | 发布时间 |
| list.favorited | boolean | 当前登录用户是否已收藏（未登录返回 false） |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 3001 | 新闻不存在或已下架 |
说明
个人中心接口作用于当前令牌所属的用户，无需在路径中传用户 ID。
分页从第 1 页开始，
pageSize 上限 100、超出会被下取；total 是满足条件的记录总数，与当前页长度无关。需在请求头携带
Authorization: Bearer ；令牌过期请先用刷新令牌接口换取新的访问令牌。个人信息
收藏新闻
把一条新闻加入当前用户的收藏夹。重复收藏返回 3005。
接口概要
鉴权要求
需登录（缺少有效令牌返回 401）
请求内容类型
—
响应内容类型
application/json
幂等性
非幂等，重复提交会产生多条数据
响应数据模型
基本类型 / 空值
所属模块
个人信息
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| newsId | integer | 必填 | 新闻 ID |
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X POST 'https://boot.qingwu.ink/api/v1/users/me/favorites/1' -H 'Accept: application/json' -H 'Authorization: Bearer <accessToken>'
const res = await fetch('https://boot.qingwu.ink/api/v1/users/me/favorites/1', {
method: 'POST',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`,
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.post(
"https://boot.qingwu.ink/api/v1/users/me/favorites/1",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {access_token}",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/users/me/favorites/1"))
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.POST()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("POST", "https://boot.qingwu.ink/api/v1/users/me/favorites/1", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer " + accessToken)
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/users/me/favorites/1");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Authorization: Bearer " . $accessToken,
],
]);
echo curl_exec($ch);
curl_close($ch);POST /api/v1/users/me/favorites/1 HTTP/1.1 Host: boot.qingwu.ink Authorization: Bearer <accessToken> Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "收藏成功",
"data": null,
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明
该接口的 data 为基本类型或空值，没有可展开的字段。
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 201 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 404 | 路径中的资源 ID 在库中不存在 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 3001 | 新闻不存在或已下架 |
说明
个人中心接口作用于当前令牌所属的用户，无需在路径中传用户 ID。
需在请求头携带
Authorization: Bearer ；令牌过期请先用刷新令牌接口换取新的访问令牌。个人信息
取消收藏
移出收藏夹。若原本未收藏则返回 3006。
接口概要
鉴权要求
需登录（缺少有效令牌返回 401）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
基本类型 / 空值
所属模块
个人信息
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| newsId | integer | 必填 | 新闻 ID |
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X DELETE 'https://boot.qingwu.ink/api/v1/users/me/favorites/1' -H 'Accept: application/json' -H 'Authorization: Bearer <accessToken>'
const res = await fetch('https://boot.qingwu.ink/api/v1/users/me/favorites/1', {
method: 'DELETE',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`,
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.delete(
"https://boot.qingwu.ink/api/v1/users/me/favorites/1",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {access_token}",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/users/me/favorites/1"))
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.DELETE()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("DELETE", "https://boot.qingwu.ink/api/v1/users/me/favorites/1", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer " + accessToken)
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/users/me/favorites/1");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "DELETE",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Authorization: Bearer " . $accessToken,
],
]);
echo curl_exec($ch);
curl_close($ch);DELETE /api/v1/users/me/favorites/1 HTTP/1.1 Host: boot.qingwu.ink Authorization: Bearer <accessToken> Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "已取消收藏",
"data": null,
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明
该接口的 data 为基本类型或空值，没有可展开的字段。
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 404 | 路径中的资源 ID 在库中不存在 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 3001 | 新闻不存在或已下架 |
说明
个人中心接口作用于当前令牌所属的用户，无需在路径中传用户 ID。
需在请求头携带
Authorization: Bearer ；令牌过期请先用刷新令牌接口换取新的访问令牌。个人信息
收藏状态
查询指定新闻是否已被当前用户收藏，适合详情页按钮初始化。
接口概要
鉴权要求
需登录（缺少有效令牌返回 401）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
基本类型 / 空值
所属模块
个人信息
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| newsId | integer | 必填 | 新闻 ID |
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X GET 'https://boot.qingwu.ink/api/v1/users/me/favorites/1/status' -H 'Accept: application/json' -H 'Authorization: Bearer <accessToken>'
const res = await fetch('https://boot.qingwu.ink/api/v1/users/me/favorites/1/status', {
method: 'GET',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`,
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/users/me/favorites/1/status",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {access_token}",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/users/me/favorites/1/status"))
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/users/me/favorites/1/status", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer " + accessToken)
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/users/me/favorites/1/status");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Authorization: Bearer " . $accessToken,
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/users/me/favorites/1/status HTTP/1.1 Host: boot.qingwu.ink Authorization: Bearer <accessToken> Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": true,
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明
该接口的 data 为基本类型或空值，没有可展开的字段。
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 404 | 路径中的资源 ID 在库中不存在 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 3001 | 新闻不存在或已下架 |
说明
个人中心接口作用于当前令牌所属的用户，无需在路径中传用户 ID。
需在请求头携带
Authorization: Bearer ；令牌过期请先用刷新令牌接口换取新的访问令牌。个人信息
我的评论
分页返回当前用户发表过的评论，按时间倒序。
接口概要
鉴权要求
需登录（缺少有效令牌返回 401）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
PageResult<CommentVO>
所属模块
个人信息
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| pageNum | integer | 可选 | 页码，从 1 开始 例如 1 |
| pageSize | integer | 可选 | 每页条数，最大 100 例如 10 |
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X GET 'https://boot.qingwu.ink/api/v1/users/me/comments?pageNum=1&pageSize=10' -H 'Accept: application/json' -H 'Authorization: Bearer <accessToken>'
const res = await fetch('https://boot.qingwu.ink/api/v1/users/me/comments?pageNum=1&pageSize=10', {
method: 'GET',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`,
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/users/me/comments?pageNum=1&pageSize=10",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {access_token}",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/users/me/comments?pageNum=1&pageSize=10"))
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/users/me/comments?pageNum=1&pageSize=10", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer " + accessToken)
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/users/me/comments?pageNum=1&pageSize=10");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Authorization: Bearer " . $accessToken,
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/users/me/comments?pageNum=1&pageSize=10 HTTP/1.1 Host: boot.qingwu.ink Authorization: Bearer <accessToken> Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": {
"pageNum": 1,
"pageSize": 5,
"total": 6,
"pages": 2,
"list": [
{
"id": 1,
"newsId": 4,
"userId": 2,
"nickname": "演示用户",
"avatar": null,
"parentId": 0,
"replyToNickname": null,
"content": "数据比预期更稳健。",
"likeCount": 0,
"createTime": "2026-10-16 09:31:07",
"children": [
{
"id": 2,
"newsId": 4,
"userId": 1,
"nickname": "系统管理员",
"avatar": null,
"parentId": 1,
"replyToNickname": "演示用户",
"content": "同意，后续走势值得持续观察。",
"likeCount": 0,
"createTime": "2026-10-16 09:32:44",
"children": []
}
]
}
]
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 PageResult<CommentVO>
| 字段 | 类型 | 说明 |
|---|---|---|
| pageNum | integer | 当前页码 |
| pageSize | integer | 每页条数 |
| total | integer | 记录总数 |
| pages | integer | 总页数 |
| list | array<CommentVO> | 当前页的数据集合 |
| list.id | integer | 评论 ID |
| list.newsId | integer | 新闻 ID |
| list.userId | integer | 评论用户 ID |
| list.nickname | string | 评论用户昵称 |
| list.avatar | string | 评论用户头像 |
| list.parentId | integer | 父评论 ID，0 表示一级评论 |
| list.replyToNickname | string | 被回复用户昵称 |
| list.content | string | 评论内容 |
| list.likeCount | integer | 点赞数 |
| list.createTime | string | 评论时间 |
| list.children | array<CommentVO> | 子回复列表 |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 3001 | 新闻不存在或已下架 |
说明
个人中心接口作用于当前令牌所属的用户，无需在路径中传用户 ID。
分页从第 1 页开始，
pageSize 上限 100、超出会被下取；total 是满足条件的记录总数，与当前页长度无关。需在请求头携带
Authorization: Bearer ；令牌过期请先用刷新令牌接口换取新的访问令牌。个人信息
我的统计
个人维度的计数信息，当前包含收藏总数。
接口概要
鉴权要求
需登录（缺少有效令牌返回 401）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
UserStatisticsVO
所属模块
个人信息
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X GET 'https://boot.qingwu.ink/api/v1/users/me/statistics' -H 'Accept: application/json' -H 'Authorization: Bearer <accessToken>'
const res = await fetch('https://boot.qingwu.ink/api/v1/users/me/statistics', {
method: 'GET',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`,
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/users/me/statistics",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {access_token}",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/users/me/statistics"))
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/users/me/statistics", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer " + accessToken)
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/users/me/statistics");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Authorization: Bearer " . $accessToken,
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/users/me/statistics HTTP/1.1 Host: boot.qingwu.ink Authorization: Bearer <accessToken> Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": {
"favoriteCount": 12
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 UserStatisticsVO
| 字段 | 类型 | 说明 |
|---|---|---|
| favoriteCount | integer | 收藏的新闻数量 |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
说明
个人中心接口作用于当前令牌所属的用户，无需在路径中传用户 ID。
需在请求头携带
Authorization: Bearer ；令牌过期请先用刷新令牌接口换取新的访问令牌。个人信息
注销账号
永久删除当前账号及其收藏记录，该操作不可撤销。
接口概要
鉴权要求
需登录（缺少有效令牌返回 401）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
基本类型 / 空值
所属模块
个人信息
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X DELETE 'https://boot.qingwu.ink/api/v1/users/me' -H 'Accept: application/json' -H 'Authorization: Bearer <accessToken>'
const res = await fetch('https://boot.qingwu.ink/api/v1/users/me', {
method: 'DELETE',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`,
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.delete(
"https://boot.qingwu.ink/api/v1/users/me",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {access_token}",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/users/me"))
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.DELETE()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("DELETE", "https://boot.qingwu.ink/api/v1/users/me", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer " + accessToken)
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/users/me");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "DELETE",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Authorization: Bearer " . $accessToken,
],
]);
echo curl_exec($ch);
curl_close($ch);DELETE /api/v1/users/me HTTP/1.1 Host: boot.qingwu.ink Authorization: Bearer <accessToken> Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "账号已注销",
"data": null,
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明
该接口的 data 为基本类型或空值，没有可展开的字段。
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
说明
个人中心接口作用于当前令牌所属的用户，无需在路径中传用户 ID。
需在请求头携带
Authorization: Bearer ；令牌过期请先用刷新令牌接口换取新的访问令牌。用户管理
用户列表
管理端分页检索用户，支持按用户名、昵称、邮箱、手机号关键词及角色、状态过滤。
接口概要
鉴权要求
仅管理员（缺少有效令牌返回 401）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
PageResult<UserVO>
所属模块
用户管理
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| pageNum | integer | 可选 | 页码，从 1 开始 例如 1 |
| pageSize | integer | 可选 | 每页条数，最大 100 例如 10 |
| keyword | string | 可选 | 关键词，模糊匹配 |
| role | string | 可选 | 角色，取值为 USER 或 ADMIN |
| status | integer | 可选 | 状态。用户：1 正常 / 0 禁用；新闻：0 草稿 / 1 已发布 / 2 下架 |
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X GET 'https://boot.qingwu.ink/api/v1/users' -H 'Accept: application/json' -H 'Authorization: Bearer <accessToken>'
const res = await fetch('https://boot.qingwu.ink/api/v1/users', {
method: 'GET',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`,
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/users",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {access_token}",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/users"))
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/users", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer " + accessToken)
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/users");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Authorization: Bearer " . $accessToken,
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/users HTTP/1.1 Host: boot.qingwu.ink Authorization: Bearer <accessToken> Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": {
"pageNum": 1,
"pageSize": 5,
"total": 2,
"pages": 1,
"list": [
{
"id": 1,
"username": "admin",
"nickname": "系统管理员",
"email": "admin@example.com",
"phone": "13800000000",
"avatar": null,
"gender": 1,
"birthday": null,
"provinceId": 110000,
"provinceName": "北京市",
"cityId": 110100,
"cityName": "市辖区",
"districtId": 110105,
"districtName": "朝阳区",
"signature": "保持简洁",
"role": "ADMIN",
"status": 1,
"lastLoginTime": "2026-10-16 09:23:12",
"createTime": "2026-10-16 08:59:41"
}
]
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 PageResult<UserVO>
| 字段 | 类型 | 说明 |
|---|---|---|
| pageNum | integer | 当前页码 |
| pageSize | integer | 每页条数 |
| total | integer | 记录总数 |
| pages | integer | 总页数 |
| list | array<UserVO> | 当前页的数据集合 |
| list.id | integer | 用户 ID 例如 1 |
| list.username | string | 用户名 例如 admin |
| list.nickname | string | 昵称 例如 系统管理员 |
| list.email | string | 邮箱 例如 admin@example.com |
| list.phone | string | 手机号 例如 13800000000 |
| list.avatar | string | 头像 URL |
| list.gender | integer | 性别：0-未知 1-男 2-女 例如 1 |
| list.birthday | string | 生日 |
| list.provinceId | integer | 省份 ID 例如 110000 |
| list.provinceName | string | 省份名称 例如 北京市 |
| list.cityId | integer | 城市 ID 例如 110100 |
| list.cityName | string | 城市名称 例如 市辖区 |
| list.districtId | integer | 区县 ID 例如 110105 |
| list.districtName | string | 区县名称 例如 朝阳区 |
| list.address | string | 详细地址 |
| list.signature | string | 个性签名 |
| list.role | string | 角色 例如 ADMIN |
| list.status | integer | 状态：1-正常 0-禁用 例如 1 |
| list.lastLoginTime | string | 最近登录时间 |
| list.createTime | string | 注册时间 |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 403 | 已登录但不是管理员；或账号被禁用 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
说明
本组接口需要管理员角色，普通用户访问会返回 403。
分页从第 1 页开始，
pageSize 上限 100、超出会被下取；total 是满足条件的记录总数，与当前页长度无关。该接口要求管理员角色：普通用户即使携带有效令牌也会被拒绝（HTTP 403，业务码
1011）。用户管理
查询用户公开信息
按用户 ID 查询公开资料，无需登录。返回字段与个人中心一致。
接口概要
鉴权要求
公开（无需令牌）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
UserVO
所属模块
用户管理
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | integer | 必填 | 资源 ID |
请求示例7 种语言
该接口无需令牌，可直接调用。把示例中的参数值换成你的实际值即可。
curl -X GET 'https://boot.qingwu.ink/api/v1/users/1' -H 'Accept: application/json'
const res = await fetch('https://boot.qingwu.ink/api/v1/users/1', {
method: 'GET',
headers: {
'Accept': 'application/json',
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/users/1",
headers={
"Accept": "application/json",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/users/1"))
.header("Accept", "application/json")
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/users/1", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/users/1");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/users/1 HTTP/1.1 Host: boot.qingwu.ink Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": {
"id": 1,
"username": "admin",
"nickname": "系统管理员",
"email": "admin@example.com",
"phone": "13800000000",
"avatar": null,
"gender": 1,
"birthday": null,
"provinceId": 110000,
"provinceName": "北京市",
"cityId": 110100,
"cityName": "市辖区",
"districtId": 110105,
"districtName": "朝阳区",
"signature": "保持简洁",
"role": "ADMIN",
"status": 1,
"lastLoginTime": "2026-10-16 09:23:12",
"createTime": "2026-10-16 08:59:41"
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 UserVO
| 字段 | 类型 | 说明 |
|---|---|---|
| id | integer | 用户 ID 例如 1 |
| username | string | 用户名 例如 admin |
| nickname | string | 昵称 例如 系统管理员 |
| string | 邮箱 例如 admin@example.com | |
| phone | string | 手机号 例如 13800000000 |
| avatar | string | 头像 URL |
| gender | integer | 性别：0-未知 1-男 2-女 例如 1 |
| birthday | string | 生日 |
| provinceId | integer | 省份 ID 例如 110000 |
| provinceName | string | 省份名称 例如 北京市 |
| cityId | integer | 城市 ID 例如 110100 |
| cityName | string | 城市名称 例如 市辖区 |
| districtId | integer | 区县 ID 例如 110105 |
| districtName | string | 区县名称 例如 朝阳区 |
| address | string | 详细地址 |
| signature | string | 个性签名 |
| role | string | 角色 例如 ADMIN |
| status | integer | 状态：1-正常 0-禁用 例如 1 |
| lastLoginTime | string | 最近登录时间 |
| createTime | string | 注册时间 |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 404 | 路径中的资源 ID 在库中不存在 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 1004 | 用户不存在 |
说明
本组接口需要管理员角色，普通用户访问会返回 403。
用户不存在时返回
1004 与 HTTP 404。用户管理
修改用户角色
在 USER 与 ADMIN 之间切换角色，取值不合法时返回 400。
接口概要
鉴权要求
仅管理员（缺少有效令牌返回 401）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
UserVO
所属模块
用户管理
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | integer | 必填 | 资源 ID |
| role | string | 必填 | 角色，取值为 USER 或 ADMIN |
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X PUT 'https://boot.qingwu.ink/api/v1/users/1/role' -H 'Accept: application/json' -H 'Authorization: Bearer <accessToken>'
const res = await fetch('https://boot.qingwu.ink/api/v1/users/1/role', {
method: 'PUT',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`,
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.put(
"https://boot.qingwu.ink/api/v1/users/1/role",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {access_token}",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/users/1/role"))
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.PUT()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("PUT", "https://boot.qingwu.ink/api/v1/users/1/role", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer " + accessToken)
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/users/1/role");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Authorization: Bearer " . $accessToken,
],
]);
echo curl_exec($ch);
curl_close($ch);PUT /api/v1/users/1/role HTTP/1.1 Host: boot.qingwu.ink Authorization: Bearer <accessToken> Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": {
"id": 1,
"username": "admin",
"nickname": "系统管理员",
"email": "admin@example.com",
"phone": "13800000000",
"avatar": null,
"gender": 1,
"birthday": null,
"provinceId": 110000,
"provinceName": "北京市",
"cityId": 110100,
"cityName": "市辖区",
"districtId": 110105,
"districtName": "朝阳区",
"signature": "保持简洁",
"role": "ADMIN",
"status": 1,
"lastLoginTime": "2026-10-16 09:23:12",
"createTime": "2026-10-16 08:59:41"
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 UserVO
| 字段 | 类型 | 说明 |
|---|---|---|
| id | integer | 用户 ID 例如 1 |
| username | string | 用户名 例如 admin |
| nickname | string | 昵称 例如 系统管理员 |
| string | 邮箱 例如 admin@example.com | |
| phone | string | 手机号 例如 13800000000 |
| avatar | string | 头像 URL |
| gender | integer | 性别：0-未知 1-男 2-女 例如 1 |
| birthday | string | 生日 |
| provinceId | integer | 省份 ID 例如 110000 |
| provinceName | string | 省份名称 例如 北京市 |
| cityId | integer | 城市 ID 例如 110100 |
| cityName | string | 城市名称 例如 市辖区 |
| districtId | integer | 区县 ID 例如 110105 |
| districtName | string | 区县名称 例如 朝阳区 |
| address | string | 详细地址 |
| signature | string | 个性签名 |
| role | string | 角色 例如 ADMIN |
| status | integer | 状态：1-正常 0-禁用 例如 1 |
| lastLoginTime | string | 最近登录时间 |
| createTime | string | 注册时间 |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 403 | 已登录但不是管理员；或账号被禁用 |
| 404 | 路径中的资源 ID 在库中不存在 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 1004 | 用户不存在 |
| 1011 | 该操作需要管理员权限 |
说明
本组接口需要管理员角色，普通用户访问会返回 403。
不能把当前登录账号降级为普通用户。
用户管理
启用或禁用用户
status = 1 启用，status = 0 禁用。被禁用的账号无法登录，但数据保留。
接口概要
鉴权要求
仅管理员（缺少有效令牌返回 401）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
UserVO
所属模块
用户管理
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | integer | 必填 | 资源 ID |
| status | integer | 必填 | 状态。用户：1 正常 / 0 禁用；新闻：0 草稿 / 1 已发布 / 2 下架 |
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X PUT 'https://boot.qingwu.ink/api/v1/users/1/status?status=1' -H 'Accept: application/json' -H 'Authorization: Bearer <accessToken>'
const res = await fetch('https://boot.qingwu.ink/api/v1/users/1/status?status=1', {
method: 'PUT',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`,
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.put(
"https://boot.qingwu.ink/api/v1/users/1/status?status=1",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {access_token}",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/users/1/status?status=1"))
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.PUT()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("PUT", "https://boot.qingwu.ink/api/v1/users/1/status?status=1", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer " + accessToken)
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/users/1/status?status=1");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Authorization: Bearer " . $accessToken,
],
]);
echo curl_exec($ch);
curl_close($ch);PUT /api/v1/users/1/status?status=1 HTTP/1.1 Host: boot.qingwu.ink Authorization: Bearer <accessToken> Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": {
"id": 1,
"username": "admin",
"nickname": "系统管理员",
"email": "admin@example.com",
"phone": "13800000000",
"avatar": null,
"gender": 1,
"birthday": null,
"provinceId": 110000,
"provinceName": "北京市",
"cityId": 110100,
"cityName": "市辖区",
"districtId": 110105,
"districtName": "朝阳区",
"signature": "保持简洁",
"role": "ADMIN",
"status": 1,
"lastLoginTime": "2026-10-16 09:23:12",
"createTime": "2026-10-16 08:59:41"
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 UserVO
| 字段 | 类型 | 说明 |
|---|---|---|
| id | integer | 用户 ID 例如 1 |
| username | string | 用户名 例如 admin |
| nickname | string | 昵称 例如 系统管理员 |
| string | 邮箱 例如 admin@example.com | |
| phone | string | 手机号 例如 13800000000 |
| avatar | string | 头像 URL |
| gender | integer | 性别：0-未知 1-男 2-女 例如 1 |
| birthday | string | 生日 |
| provinceId | integer | 省份 ID 例如 110000 |
| provinceName | string | 省份名称 例如 北京市 |
| cityId | integer | 城市 ID 例如 110100 |
| cityName | string | 城市名称 例如 市辖区 |
| districtId | integer | 区县 ID 例如 110105 |
| districtName | string | 区县名称 例如 朝阳区 |
| address | string | 详细地址 |
| signature | string | 个性签名 |
| role | string | 角色 例如 ADMIN |
| status | integer | 状态：1-正常 0-禁用 例如 1 |
| lastLoginTime | string | 最近登录时间 |
| createTime | string | 注册时间 |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 403 | 已登录但不是管理员；或账号被禁用 |
| 404 | 路径中的资源 ID 在库中不存在 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 1004 | 用户不存在 |
说明
本组接口需要管理员角色，普通用户访问会返回 403。
不能禁用当前登录账号，否则返回
400。用户管理
删除用户
管理端删除指定用户，不可撤销。
接口概要
鉴权要求
仅管理员（缺少有效令牌返回 401）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
基本类型 / 空值
所属模块
用户管理
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | integer | 必填 | 资源 ID |
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X DELETE 'https://boot.qingwu.ink/api/v1/users/1' -H 'Accept: application/json' -H 'Authorization: Bearer <accessToken>'
const res = await fetch('https://boot.qingwu.ink/api/v1/users/1', {
method: 'DELETE',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`,
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.delete(
"https://boot.qingwu.ink/api/v1/users/1",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {access_token}",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/users/1"))
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.DELETE()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("DELETE", "https://boot.qingwu.ink/api/v1/users/1", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer " + accessToken)
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/users/1");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "DELETE",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Authorization: Bearer " . $accessToken,
],
]);
echo curl_exec($ch);
curl_close($ch);DELETE /api/v1/users/1 HTTP/1.1 Host: boot.qingwu.ink Authorization: Bearer <accessToken> Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "用户已删除",
"data": null,
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明
该接口的 data 为基本类型或空值，没有可展开的字段。
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 403 | 已登录但不是管理员；或账号被禁用 |
| 404 | 路径中的资源 ID 在库中不存在 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 1004 | 用户不存在 |
说明
本组接口需要管理员角色，普通用户访问会返回 403。
不能删除当前登录账号。
省市区
获取全部省份
返回 34 个省级行政区，已按排序值排好序，可直接用于下拉框。
接口概要
鉴权要求
公开（无需令牌）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
array<Region>
所属模块
省市区
请求示例7 种语言
该接口无需令牌，可直接调用。把示例中的参数值换成你的实际值即可。
curl -X GET 'https://boot.qingwu.ink/api/v1/regions/provinces' -H 'Accept: application/json'
const res = await fetch('https://boot.qingwu.ink/api/v1/regions/provinces', {
method: 'GET',
headers: {
'Accept': 'application/json',
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/regions/provinces",
headers={
"Accept": "application/json",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/regions/provinces"))
.header("Accept", "application/json")
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/regions/provinces", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/regions/provinces");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/regions/provinces HTTP/1.1 Host: boot.qingwu.ink Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": [
{
"id": 110000,
"parentId": 0,
"name": "北京市",
"shortName": "京",
"level": 1,
"code": "110000",
"pinyin": "beijingshi",
"sort": 1,
"status": 1
},
{
"id": 440000,
"parentId": 0,
"name": "广东省",
"shortName": "粤",
"level": 1,
"code": "440000",
"pinyin": "guangdongsheng",
"sort": 19,
"status": 1
}
],
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 array<Region>
| 字段 | 类型 | 说明 |
|---|---|---|
| id | integer | 地区 ID（行政区划代码） 例如 110000 |
| parentId | integer | 上级地区 ID，顶级为 0 例如 0 |
| name | string | 地区名称 例如 北京市 |
| shortName | string | 简称 例如 京 |
| level | integer | 层级：1-省 2-市 3-区县 例如 1 |
| code | string | 行政区划代码字符串 例如 110000 |
| zipCode | string | 邮政编码 |
| areaCode | string | 电话区号 例如 010 |
| lng | number | 经度 |
| lat | number | 纬度 |
| pinyin | string | 拼音（支持拼音搜索） 例如 beijingshi |
| sort | integer | 排序值 |
| status | integer | 状态：1-启用 0-停用 |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 2001 | 地区不存在 |
| 2002 | 地区层级不正确 |
| 2003 | 该地区下存在子区域，无法删除 |
说明
该接口为公开接口，无需任何凭证即可调用。
省市区
获取省份下的城市
返回指定省份的全部地级行政区，用于省 → 市级联的第二步。
接口概要
鉴权要求
公开（无需令牌）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
array<Region>
所属模块
省市区
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| provinceId | integer | 必填 | 省份 ID，如 440000 |
请求示例7 种语言
该接口无需令牌，可直接调用。把示例中的参数值换成你的实际值即可。
curl -X GET 'https://boot.qingwu.ink/api/v1/regions/cities?provinceId=1' -H 'Accept: application/json'
const res = await fetch('https://boot.qingwu.ink/api/v1/regions/cities?provinceId=1', {
method: 'GET',
headers: {
'Accept': 'application/json',
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/regions/cities?provinceId=1",
headers={
"Accept": "application/json",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/regions/cities?provinceId=1"))
.header("Accept", "application/json")
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/regions/cities?provinceId=1", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/regions/cities?provinceId=1");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/regions/cities?provinceId=1 HTTP/1.1 Host: boot.qingwu.ink Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": [
{
"id": 440300,
"parentId": 440000,
"name": "深圳市",
"shortName": null,
"level": 2,
"code": "440300",
"areaCode": null,
"pinyin": "shenzhenshi",
"sort": 3,
"status": 1
}
],
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 array<Region>
| 字段 | 类型 | 说明 |
|---|---|---|
| id | integer | 地区 ID（行政区划代码） 例如 110000 |
| parentId | integer | 上级地区 ID，顶级为 0 例如 0 |
| name | string | 地区名称 例如 北京市 |
| shortName | string | 简称 例如 京 |
| level | integer | 层级：1-省 2-市 3-区县 例如 1 |
| code | string | 行政区划代码字符串 例如 110000 |
| zipCode | string | 邮政编码 |
| areaCode | string | 电话区号 例如 010 |
| lng | number | 经度 |
| lat | number | 纬度 |
| pinyin | string | 拼音（支持拼音搜索） 例如 beijingshi |
| sort | integer | 排序值 |
| status | integer | 状态：1-启用 0-停用 |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 2001 | 地区不存在 |
| 2002 | 地区层级不正确 |
| 2003 | 该地区下存在子区域，无法删除 |
说明
该接口为公开接口，无需任何凭证即可调用。
省市区
获取城市下的区县
返回指定城市的全部区县级行政区，用于市 → 区县级联的第三步。
接口概要
鉴权要求
公开（无需令牌）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
array<Region>
所属模块
省市区
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| cityId | integer | 必填 | 城市 ID，如 440300 |
请求示例7 种语言
该接口无需令牌，可直接调用。把示例中的参数值换成你的实际值即可。
curl -X GET 'https://boot.qingwu.ink/api/v1/regions/districts?cityId=1' -H 'Accept: application/json'
const res = await fetch('https://boot.qingwu.ink/api/v1/regions/districts?cityId=1', {
method: 'GET',
headers: {
'Accept': 'application/json',
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/regions/districts?cityId=1",
headers={
"Accept": "application/json",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/regions/districts?cityId=1"))
.header("Accept", "application/json")
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/regions/districts?cityId=1", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/regions/districts?cityId=1");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/regions/districts?cityId=1 HTTP/1.1 Host: boot.qingwu.ink Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": [
{
"id": 440303,
"parentId": 440300,
"name": "罗湖区",
"level": 3,
"code": "440303",
"pinyin": "luohuqu",
"sort": 1,
"status": 1
},
{
"id": 440304,
"parentId": 440300,
"name": "福田区",
"level": 3,
"code": "440304",
"pinyin": "futianqu",
"sort": 2,
"status": 1
}
],
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 array<Region>
| 字段 | 类型 | 说明 |
|---|---|---|
| id | integer | 地区 ID（行政区划代码） 例如 110000 |
| parentId | integer | 上级地区 ID，顶级为 0 例如 0 |
| name | string | 地区名称 例如 北京市 |
| shortName | string | 简称 例如 京 |
| level | integer | 层级：1-省 2-市 3-区县 例如 1 |
| code | string | 行政区划代码字符串 例如 110000 |
| zipCode | string | 邮政编码 |
| areaCode | string | 电话区号 例如 010 |
| lng | number | 经度 |
| lat | number | 纬度 |
| pinyin | string | 拼音（支持拼音搜索） 例如 beijingshi |
| sort | integer | 排序值 |
| status | integer | 状态：1-启用 0-停用 |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 2001 | 地区不存在 |
| 2002 | 地区层级不正确 |
| 2003 | 该地区下存在子区域，无法删除 |
说明
区县数据覆盖 4 个直辖市、全部省会与首府、计划单列市及主要城市；其余城市返回空数组，可按同一格式补充。
省市区
按上级查询下级
通用级联接口，parentId 传 0 即返回全部省级行政区，无需关心层级语义。
接口概要
鉴权要求
公开（无需令牌）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
array<Region>
所属模块
省市区
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| parentId | integer | 可选 | 上级地区 ID，顶级传 0 例如 0 |
请求示例7 种语言
该接口无需令牌，可直接调用。把示例中的参数值换成你的实际值即可。
curl -X GET 'https://boot.qingwu.ink/api/v1/regions/children?parentId=0' -H 'Accept: application/json'
const res = await fetch('https://boot.qingwu.ink/api/v1/regions/children?parentId=0', {
method: 'GET',
headers: {
'Accept': 'application/json',
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/regions/children?parentId=0",
headers={
"Accept": "application/json",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/regions/children?parentId=0"))
.header("Accept", "application/json")
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/regions/children?parentId=0", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/regions/children?parentId=0");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/regions/children?parentId=0 HTTP/1.1 Host: boot.qingwu.ink Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": [
{
"id": 440300,
"parentId": 440000,
"name": "深圳市",
"shortName": null,
"level": 2,
"code": "440300",
"areaCode": null,
"pinyin": "shenzhenshi",
"sort": 3,
"status": 1
}
],
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 array<Region>
| 字段 | 类型 | 说明 |
|---|---|---|
| id | integer | 地区 ID（行政区划代码） 例如 110000 |
| parentId | integer | 上级地区 ID，顶级为 0 例如 0 |
| name | string | 地区名称 例如 北京市 |
| shortName | string | 简称 例如 京 |
| level | integer | 层级：1-省 2-市 3-区县 例如 1 |
| code | string | 行政区划代码字符串 例如 110000 |
| zipCode | string | 邮政编码 |
| areaCode | string | 电话区号 例如 010 |
| lng | number | 经度 |
| lat | number | 纬度 |
| pinyin | string | 拼音（支持拼音搜索） 例如 beijingshi |
| sort | integer | 排序值 |
| status | integer | 状态：1-启用 0-停用 |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 2001 | 地区不存在 |
| 2002 | 地区层级不正确 |
| 2003 | 该地区下存在子区域，无法删除 |
说明
该接口为公开接口，无需任何凭证即可调用。
省市区
获取地区树
一次性返回省—市—区县三级嵌套结构，适合离线渲染整棵级联树。
接口概要
鉴权要求
公开（无需令牌）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
array<RegionTreeVO>
所属模块
省市区
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| parentId | integer | 可选 | 上级地区 ID，顶级传 0 例如 0 |
| depth | integer | 可选 | 树形展开深度，1–3，默认 3 例如 3 |
请求示例7 种语言
该接口无需令牌，可直接调用。把示例中的参数值换成你的实际值即可。
curl -X GET 'https://boot.qingwu.ink/api/v1/regions/tree?parentId=0&depth=3' -H 'Accept: application/json'
const res = await fetch('https://boot.qingwu.ink/api/v1/regions/tree?parentId=0&depth=3', {
method: 'GET',
headers: {
'Accept': 'application/json',
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/regions/tree?parentId=0&depth=3",
headers={
"Accept": "application/json",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/regions/tree?parentId=0&depth=3"))
.header("Accept", "application/json")
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/regions/tree?parentId=0&depth=3", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/regions/tree?parentId=0&depth=3");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/regions/tree?parentId=0&depth=3 HTTP/1.1 Host: boot.qingwu.ink Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": [
{
"id": 440000,
"parentId": 0,
"name": "广东省",
"shortName": "粤",
"level": 1,
"code": "440000",
"pinyin": "guangdongsheng",
"children": [
{
"id": 440300,
"parentId": 440000,
"name": "深圳市",
"level": 2,
"code": "440300",
"pinyin": "shenzhenshi",
"children": [
{
"id": 440303,
"parentId": 440300,
"name": "罗湖区",
"level": 3,
"code": "440303",
"pinyin": "luohuqu",
"children": []
}
]
}
]
}
],
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 array<RegionTreeVO>
| 字段 | 类型 | 说明 |
|---|---|---|
| id | integer | 地区 ID 例如 110000 |
| parentId | integer | 上级地区 ID 例如 0 |
| name | string | 地区名称 例如 北京市 |
| shortName | string | 简称 例如 京 |
| level | integer | 层级：1-省 2-市 3-区县 例如 1 |
| code | string | 行政区划代码 例如 110000 |
| pinyin | string | 拼音 |
| children | array<RegionTreeVO> | 子节点 |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 2001 | 地区不存在 |
| 2002 | 地区层级不正确 |
| 2003 | 该地区下存在子区域，无法删除 |
说明
depth 最大为 3。数据量较大时建议改用逐级查询接口，减少单次响应体积。省市区
搜索地区
按中文名称、拼音或简称模糊匹配。拼音搜索可让用户输入 shenzhen 直接命中「深圳市」。
接口概要
鉴权要求
公开（无需令牌）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
array<Region>
所属模块
省市区
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| keyword | string | 必填 | 关键词，模糊匹配 |
| limit | integer | 可选 | 返回条数上限 例如 20 |
请求示例7 种语言
该接口无需令牌，可直接调用。把示例中的参数值换成你的实际值即可。
curl -X GET 'https://boot.qingwu.ink/api/v1/regions/search?limit=20' -H 'Accept: application/json'
const res = await fetch('https://boot.qingwu.ink/api/v1/regions/search?limit=20', {
method: 'GET',
headers: {
'Accept': 'application/json',
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/regions/search?limit=20",
headers={
"Accept": "application/json",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/regions/search?limit=20"))
.header("Accept", "application/json")
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/regions/search?limit=20", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/regions/search?limit=20");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/regions/search?limit=20 HTTP/1.1 Host: boot.qingwu.ink Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": [
{
"id": 440300,
"parentId": 440000,
"name": "深圳市",
"shortName": null,
"level": 2,
"code": "440300",
"areaCode": null,
"pinyin": "shenzhenshi",
"sort": 3,
"status": 1
}
],
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 array<Region>
| 字段 | 类型 | 说明 |
|---|---|---|
| id | integer | 地区 ID（行政区划代码） 例如 110000 |
| parentId | integer | 上级地区 ID，顶级为 0 例如 0 |
| name | string | 地区名称 例如 北京市 |
| shortName | string | 简称 例如 京 |
| level | integer | 层级：1-省 2-市 3-区县 例如 1 |
| code | string | 行政区划代码字符串 例如 110000 |
| zipCode | string | 邮政编码 |
| areaCode | string | 电话区号 例如 010 |
| lng | number | 经度 |
| lat | number | 纬度 |
| pinyin | string | 拼音（支持拼音搜索） 例如 beijingshi |
| sort | integer | 排序值 |
| status | integer | 状态：1-启用 0-停用 |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 2001 | 地区不存在 |
| 2002 | 地区层级不正确 |
| 2003 | 该地区下存在子区域，无法删除 |
说明
匹配范围包含
name、pinyin 与 shortName 三个字段，因此「粤」「guangdong」也能命中广东省。省市区
查询地区详情
按地区 ID 返回单条行政区划记录。地区 ID 即国家行政区划代码。
接口概要
鉴权要求
公开（无需令牌）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
Region
所属模块
省市区
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | integer | 必填 | 资源 ID |
请求示例7 种语言
该接口无需令牌，可直接调用。把示例中的参数值换成你的实际值即可。
curl -X GET 'https://boot.qingwu.ink/api/v1/regions/1' -H 'Accept: application/json'
const res = await fetch('https://boot.qingwu.ink/api/v1/regions/1', {
method: 'GET',
headers: {
'Accept': 'application/json',
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/regions/1",
headers={
"Accept": "application/json",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/regions/1"))
.header("Accept", "application/json")
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/regions/1", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/regions/1");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/regions/1 HTTP/1.1 Host: boot.qingwu.ink Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": {
"id": 440300,
"parentId": 440000,
"name": "深圳市",
"shortName": null,
"level": 2,
"code": "440300",
"areaCode": null,
"pinyin": "shenzhenshi",
"sort": 3,
"status": 1
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 Region
| 字段 | 类型 | 说明 |
|---|---|---|
| id | integer | 地区 ID（行政区划代码） 例如 110000 |
| parentId | integer | 上级地区 ID，顶级为 0 例如 0 |
| name | string | 地区名称 例如 北京市 |
| shortName | string | 简称 例如 京 |
| level | integer | 层级：1-省 2-市 3-区县 例如 1 |
| code | string | 行政区划代码字符串 例如 110000 |
| zipCode | string | 邮政编码 |
| areaCode | string | 电话区号 例如 010 |
| lng | number | 经度 |
| lat | number | 纬度 |
| pinyin | string | 拼音（支持拼音搜索） 例如 beijingshi |
| sort | integer | 排序值 |
| status | integer | 状态：1-启用 0-停用 |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 404 | 路径中的资源 ID 在库中不存在 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 2001 | 地区不存在 |
| 2002 | 地区层级不正确 |
| 2003 | 该地区下存在子区域，无法删除 |
说明
地区不存在时返回
2001 与 HTTP 404。省市区
查询地区完整路径
自顶向下回溯出「省 / 市 / 区县」链路，用于面包屑或地址回显。
接口概要
鉴权要求
公开（无需令牌）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
RegionPathVO
所属模块
省市区
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | integer | 必填 | 资源 ID |
请求示例7 种语言
该接口无需令牌，可直接调用。把示例中的参数值换成你的实际值即可。
curl -X GET 'https://boot.qingwu.ink/api/v1/regions/1/path' -H 'Accept: application/json'
const res = await fetch('https://boot.qingwu.ink/api/v1/regions/1/path', {
method: 'GET',
headers: {
'Accept': 'application/json',
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/regions/1/path",
headers={
"Accept": "application/json",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/regions/1/path"))
.header("Accept", "application/json")
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/regions/1/path", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/regions/1/path");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/regions/1/path HTTP/1.1 Host: boot.qingwu.ink Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": {
"id": 110105,
"fullName": "北京市/市辖区/朝阳区",
"path": [
{
"id": 110000,
"parentId": 0,
"name": "北京市",
"level": 1,
"code": "110000"
},
{
"id": 110100,
"parentId": 110000,
"name": "市辖区",
"level": 2,
"code": "110100"
},
{
"id": 110105,
"parentId": 110100,
"name": "朝阳区",
"level": 3,
"code": "110105"
}
]
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 RegionPathVO
| 字段 | 类型 | 说明 |
|---|---|---|
| id | integer | 地区 ID 例如 110105 |
| fullName | string | 完整路径名称 例如 北京市/市辖区/朝阳区 |
| path | array<RegionTreeVO> | 自顶向下的地区链路 |
| path.id | integer | 地区 ID 例如 110000 |
| path.parentId | integer | 上级地区 ID 例如 0 |
| path.name | string | 地区名称 例如 北京市 |
| path.shortName | string | 简称 例如 京 |
| path.level | integer | 层级：1-省 2-市 3-区县 例如 1 |
| path.code | string | 行政区划代码 例如 110000 |
| path.pinyin | string | 拼音 |
| path.children | array<RegionTreeVO> | 子节点 |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 404 | 路径中的资源 ID 在库中不存在 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 2001 | 地区不存在 |
| 2002 | 地区层级不正确 |
| 2003 | 该地区下存在子区域，无法删除 |
说明
该接口为公开接口，无需任何凭证即可调用。
省市区
新增地区
管理端新增行政区划。id 必须提供行政区划代码，层级需与上级严格对应。
接口概要
鉴权要求
仅管理员（缺少有效令牌返回 401）
请求内容类型
application/json
响应内容类型
application/json
幂等性
非幂等，重复提交会产生多条数据
响应数据模型
Region
所属模块
省市区
请求体字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | integer | 可选 | 地区 ID（行政区划代码），新增必填 例如 110000 |
| parentId | integer | 必填 | 上级地区 ID，顶级填 0 例如 0 |
| name | string | 必填 | 地区名称 例如 北京市 |
| shortName | string | 可选 | 简称 例如 京 |
| level | integer | 必填 | 层级：1-省 2-市 3-区县 例如 1 |
| zipCode | string | 可选 | 邮政编码 |
| areaCode | string | 可选 | 电话区号 例如 010 |
| lng | number | 可选 | 经度 例如 116.407526 |
| lat | number | 可选 | 纬度 例如 39.90403 |
| pinyin | string | 可选 | 拼音 |
| sort | integer | 可选 | 排序值 例如 1 |
| status | integer | 可选 | 状态：1-启用 0-停用 例如 1 |
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X POST 'https://boot.qingwu.ink/api/v1/regions'
-H 'Accept: application/json'
-H 'Authorization: Bearer <accessToken>'
-H 'Content-Type: application/json'
-d '{
"id": 123456,
"parentId": 120000,
"name": "示例区",
"level": 3,
"areaCode": "022",
"sort": 1
}'const res = await fetch('https://boot.qingwu.ink/api/v1/regions', {
method: 'POST',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(payload),
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.post(
"https://boot.qingwu.ink/api/v1/regions",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {access_token}",
"Content-Type": "application/json",
},
json=payload,
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/regions"))
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(body))
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("POST", "https://boot.qingwu.ink/api/v1/regions", strings.NewReader(body))
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer " + accessToken)
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/regions");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Authorization: Bearer " . $accessToken,
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => $body,
]);
echo curl_exec($ch);
curl_close($ch);POST /api/v1/regions HTTP/1.1
Host: boot.qingwu.ink
Authorization: Bearer <accessToken>
Accept: application/json
Content-Type: application/json
{
"id": 123456,
"parentId": 120000,
"name": "示例区",
"level": 3,
"areaCode": "022",
"sort": 1
}响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": {
"id": 440300,
"parentId": 440000,
"name": "深圳市",
"shortName": null,
"level": 2,
"code": "440300",
"areaCode": null,
"pinyin": "shenzhenshi",
"sort": 3,
"status": 1
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 Region
| 字段 | 类型 | 说明 |
|---|---|---|
| id | integer | 地区 ID（行政区划代码） 例如 110000 |
| parentId | integer | 上级地区 ID，顶级为 0 例如 0 |
| name | string | 地区名称 例如 北京市 |
| shortName | string | 简称 例如 京 |
| level | integer | 层级：1-省 2-市 3-区县 例如 1 |
| code | string | 行政区划代码字符串 例如 110000 |
| zipCode | string | 邮政编码 |
| areaCode | string | 电话区号 例如 010 |
| lng | number | 经度 |
| lat | number | 纬度 |
| pinyin | string | 拼音（支持拼音搜索） 例如 beijingshi |
| sort | integer | 排序值 |
| status | integer | 状态：1-启用 0-停用 |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 201 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 403 | 已登录但不是管理员；或账号被禁用 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 2001 | 地区不存在 |
| 2002 | 地区层级不正确 |
| 2003 | 该地区下存在子区域，无法删除 |
说明
层级不匹配（如省级下面挂市级以外的层级）返回
2002；ID 冲突返回 409。省市区
修改地区
更新地区名称、简称、区号、经纬度、拼音与排序等字段，id 本身不可修改。
接口概要
鉴权要求
仅管理员（缺少有效令牌返回 401）
请求内容类型
application/json
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
Region
所属模块
省市区
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | integer | 必填 | 资源 ID |
请求体字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | integer | 可选 | 地区 ID（行政区划代码），新增必填 例如 110000 |
| parentId | integer | 必填 | 上级地区 ID，顶级填 0 例如 0 |
| name | string | 必填 | 地区名称 例如 北京市 |
| shortName | string | 可选 | 简称 例如 京 |
| level | integer | 必填 | 层级：1-省 2-市 3-区县 例如 1 |
| zipCode | string | 可选 | 邮政编码 |
| areaCode | string | 可选 | 电话区号 例如 010 |
| lng | number | 可选 | 经度 例如 116.407526 |
| lat | number | 可选 | 纬度 例如 39.90403 |
| pinyin | string | 可选 | 拼音 |
| sort | integer | 可选 | 排序值 例如 1 |
| status | integer | 可选 | 状态：1-启用 0-停用 例如 1 |
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X PUT 'https://boot.qingwu.ink/api/v1/regions/1'
-H 'Accept: application/json'
-H 'Authorization: Bearer <accessToken>'
-H 'Content-Type: application/json'
-d '{
"parentId": 440000,
"name": "深圳市",
"level": 2,
"pinyin": "shenzhenshi",
"sort": 3
}'const res = await fetch('https://boot.qingwu.ink/api/v1/regions/1', {
method: 'PUT',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(payload),
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.put(
"https://boot.qingwu.ink/api/v1/regions/1",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {access_token}",
"Content-Type": "application/json",
},
json=payload,
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/regions/1"))
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.header("Content-Type", "application/json")
.PUT(HttpRequest.BodyPublishers.ofString(body))
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("PUT", "https://boot.qingwu.ink/api/v1/regions/1", strings.NewReader(body))
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer " + accessToken)
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/regions/1");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Authorization: Bearer " . $accessToken,
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => $body,
]);
echo curl_exec($ch);
curl_close($ch);PUT /api/v1/regions/1 HTTP/1.1
Host: boot.qingwu.ink
Authorization: Bearer <accessToken>
Accept: application/json
Content-Type: application/json
{
"parentId": 440000,
"name": "深圳市",
"level": 2,
"pinyin": "shenzhenshi",
"sort": 3
}响应示例
200 OK
{
"code": 200,
"message": "地区已更新",
"data": {
"id": 440300,
"parentId": 440000,
"name": "深圳市",
"shortName": null,
"level": 2,
"code": "440300",
"areaCode": null,
"pinyin": "shenzhenshi",
"sort": 3,
"status": 1
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 Region
| 字段 | 类型 | 说明 |
|---|---|---|
| id | integer | 地区 ID（行政区划代码） 例如 110000 |
| parentId | integer | 上级地区 ID，顶级为 0 例如 0 |
| name | string | 地区名称 例如 北京市 |
| shortName | string | 简称 例如 京 |
| level | integer | 层级：1-省 2-市 3-区县 例如 1 |
| code | string | 行政区划代码字符串 例如 110000 |
| zipCode | string | 邮政编码 |
| areaCode | string | 电话区号 例如 010 |
| lng | number | 经度 |
| lat | number | 纬度 |
| pinyin | string | 拼音（支持拼音搜索） 例如 beijingshi |
| sort | integer | 排序值 |
| status | integer | 状态：1-启用 0-停用 |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 403 | 已登录但不是管理员；或账号被禁用 |
| 404 | 路径中的资源 ID 在库中不存在 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 2001 | 地区不存在 |
| 2002 | 地区层级不正确 |
| 2003 | 该地区下存在子区域，无法删除 |
说明
字段校验在进入业务逻辑之前完成，未通过时
message 会聚合全部字段的错误提示。该接口要求管理员角色：普通用户即使携带有效令牌也会被拒绝（HTTP 403，业务码
1011）。省市区
删除地区
删除叶子节点。存在下级地区时会被拒绝，避免出现悬挂的父级引用。
接口概要
鉴权要求
仅管理员（缺少有效令牌返回 401）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
基本类型 / 空值
所属模块
省市区
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | integer | 必填 | 资源 ID |
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X DELETE 'https://boot.qingwu.ink/api/v1/regions/1' -H 'Accept: application/json' -H 'Authorization: Bearer <accessToken>'
const res = await fetch('https://boot.qingwu.ink/api/v1/regions/1', {
method: 'DELETE',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`,
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.delete(
"https://boot.qingwu.ink/api/v1/regions/1",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {access_token}",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/regions/1"))
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.DELETE()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("DELETE", "https://boot.qingwu.ink/api/v1/regions/1", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer " + accessToken)
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/regions/1");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "DELETE",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Authorization: Bearer " . $accessToken,
],
]);
echo curl_exec($ch);
curl_close($ch);DELETE /api/v1/regions/1 HTTP/1.1 Host: boot.qingwu.ink Authorization: Bearer <accessToken> Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "地区已删除",
"data": null,
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明
该接口的 data 为基本类型或空值，没有可展开的字段。
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 403 | 已登录但不是管理员；或账号被禁用 |
| 404 | 路径中的资源 ID 在库中不存在 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 2001 | 地区不存在 |
| 2002 | 地区层级不正确 |
| 2003 | 该地区下存在子区域，无法删除 |
说明
存在子区域时返回
2003 与 HTTP 409。新闻接口
新闻列表
前台分页检索，只返回已发布内容。支持分类、关键词、标签、热门、置顶与时间区间组合筛选。
接口概要
鉴权要求
公开（无需令牌）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
PageResult<NewsVO>
所属模块
新闻接口
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| pageNum | integer | 可选 | 页码，从 1 开始 例如 1 |
| pageSize | integer | 可选 | 每页条数，最大 100 例如 10 |
| categoryId | integer | 可选 | 新闻分类 ID 例如 3 |
| keyword | string | 可选 | 关键词，模糊匹配 例如 大模型 |
| tag | string | 可选 | 标签，匹配 tags 字段 例如 AI |
| status | integer | 可选 | 状态。用户：1 正常 / 0 禁用；新闻：0 草稿 / 1 已发布 / 2 下架 |
| isHot | integer | 可选 | 是否只查热门：1-是 例如 1 |
| isTop | integer | 可选 | 是否只查置顶：1-是 |
| startTime | string | 可选 | 开始时间（yyyy-MM-dd HH:mm:ss 或 yyyy-MM-dd） |
| endTime | string | 可选 | 结束时间（yyyy-MM-dd HH:mm:ss 或 yyyy-MM-dd） |
| orderBy | string | 可选 | 排序方式：latest 最新 / hot 浏览量 / like 点赞 / comment 评论 例如 latest |
请求示例7 种语言
该接口无需令牌，可直接调用。把示例中的参数值换成你的实际值即可。
curl -X GET 'https://boot.qingwu.ink/api/v1/news' -H 'Accept: application/json'
const res = await fetch('https://boot.qingwu.ink/api/v1/news', {
method: 'GET',
headers: {
'Accept': 'application/json',
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/news",
headers={
"Accept": "application/json",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/news"))
.header("Accept", "application/json")
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/news", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/news");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/news HTTP/1.1 Host: boot.qingwu.ink Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": {
"pageNum": 1,
"pageSize": 5,
"total": 25,
"pages": 5,
"list": [
{
"id": 4,
"title": "A 股三大指数集体收涨 成交额突破 1.2 万亿",
"summary": "市场情绪回暖，券商、新能源板块领涨，北向资金净流入超 60 亿元。",
"coverImage": null,
"author": "编辑部",
"source": "清吾资讯",
"categoryId": 2,
"categoryName": "财经金融",
"tags": [
"A股",
"股市"
],
"viewCount": 2155,
"likeCount": 143,
"commentCount": 0,
"isTop": 1,
"isHot": 1,
"status": 1,
"publishTime": "2026-10-16 08:54:41",
"favorited": false
}
]
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 PageResult<NewsVO>
| 字段 | 类型 | 说明 |
|---|---|---|
| pageNum | integer | 当前页码 |
| pageSize | integer | 每页条数 |
| total | integer | 记录总数 |
| pages | integer | 总页数 |
| list | array<NewsVO> | 当前页的数据集合 |
| list.id | integer | 新闻 ID 例如 1 |
| list.title | string | 标题 |
| list.summary | string | 摘要 |
| list.coverImage | string | 封面图 |
| list.author | string | 作者 |
| list.source | string | 来源 |
| list.categoryId | integer | 分类 ID 例如 3 |
| list.categoryName | string | 分类名称 例如 科技互联网 |
| list.tags | array<string> | 标签列表 |
| list.viewCount | integer | 浏览量 例如 1024 |
| list.likeCount | integer | 点赞数 例如 58 |
| list.commentCount | integer | 评论数 例如 12 |
| list.isTop | integer | 是否置顶：1-是 0-否 |
| list.isHot | integer | 是否热门：1-是 0-否 |
| list.status | integer | 状态：0-草稿 1-已发布 2-已下架 |
| list.publishTime | string | 发布时间 |
| list.favorited | boolean | 当前登录用户是否已收藏（未登录返回 false） |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 3001 | 新闻不存在或已下架 |
说明
携带合法令牌时，每条记录会带上
favorited，可直接用于渲染收藏按钮。orderBy 可选 latest、hot、like、comment；置顶内容始终排在最前。新闻接口
新闻详情
返回正文、上下篇导航与相关推荐，同时把浏览量原子加一。
接口概要
鉴权要求
公开（无需令牌）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
NewsDetailVO
所属模块
新闻接口
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | integer | 必填 | 资源 ID |
请求示例7 种语言
该接口无需令牌，可直接调用。把示例中的参数值换成你的实际值即可。
curl -X GET 'https://boot.qingwu.ink/api/v1/news/1' -H 'Accept: application/json'
const res = await fetch('https://boot.qingwu.ink/api/v1/news/1', {
method: 'GET',
headers: {
'Accept': 'application/json',
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/news/1",
headers={
"Accept": "application/json",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/news/1"))
.header("Accept", "application/json")
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/news/1", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/news/1");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/news/1 HTTP/1.1 Host: boot.qingwu.ink Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": {
"id": 4,
"title": "A 股三大指数集体收涨 成交额突破 1.2 万亿",
"summary": "市场情绪回暖，券商、新能源板块领涨，北向资金净流入超 60 亿元。",
"coverImage": null,
"author": "编辑部",
"source": "清吾资讯",
"categoryId": 2,
"categoryName": "财经金融",
"tags": [
"A股",
"股市"
],
"viewCount": 2156,
"likeCount": 143,
"commentCount": 0,
"isTop": 1,
"isHot": 1,
"status": 1,
"publishTime": "2026-10-16 08:54:41",
"favorited": false,
"content": "<h2>A 股三大指数集体收涨 成交额突破 1.2 万亿</h2><p>市场情绪回暖……</p>",
"prevId": null,
"prevTitle": null,
"nextId": 5,
"nextTitle": "央行开展 5000 亿元 MLF 操作 利率维持不变",
"liked": false
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 NewsDetailVO
| 字段 | 类型 | 说明 |
|---|---|---|
| id | integer | 新闻 ID 例如 1 |
| title | string | 标题 |
| summary | string | 摘要 |
| coverImage | string | 封面图 |
| author | string | 作者 |
| source | string | 来源 |
| categoryId | integer | 分类 ID 例如 3 |
| categoryName | string | 分类名称 例如 科技互联网 |
| tags | array<string> | 标签列表 |
| viewCount | integer | 浏览量 例如 1024 |
| likeCount | integer | 点赞数 例如 58 |
| commentCount | integer | 评论数 例如 12 |
| isTop | integer | 是否置顶：1-是 0-否 |
| isHot | integer | 是否热门：1-是 0-否 |
| status | integer | 状态：0-草稿 1-已发布 2-已下架 |
| publishTime | string | 发布时间 |
| favorited | boolean | 当前登录用户是否已收藏（未登录返回 false） |
| content | string | 正文内容 |
| prevId | integer | 上一篇新闻 ID，无则为 null |
| prevTitle | string | 上一篇新闻标题 |
| nextId | integer | 下一篇新闻 ID，无则为 null |
| nextTitle | string | 下一篇新闻标题 |
| liked | boolean | 当前登录用户是否已点赞（示例字段，可按业务接入点赞记录表） |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 404 | 路径中的资源 ID 在库中不存在 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 3001 | 新闻不存在或已下架 |
说明
浏览量采用
UPDATE ... SET view_count = view_count + 1 原子自增，并发安全。新闻不存在或已下架返回
3001 与 HTTP 404。新闻接口
热门新闻
按置顶与浏览量降序返回热点内容，适合首页榜单。
接口概要
鉴权要求
公开（无需令牌）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
array<NewsVO>
所属模块
新闻接口
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| limit | integer | 可选 | 返回条数上限 例如 10 |
请求示例7 种语言
该接口无需令牌，可直接调用。把示例中的参数值换成你的实际值即可。
curl -X GET 'https://boot.qingwu.ink/api/v1/news/hot?limit=10' -H 'Accept: application/json'
const res = await fetch('https://boot.qingwu.ink/api/v1/news/hot?limit=10', {
method: 'GET',
headers: {
'Accept': 'application/json',
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/news/hot?limit=10",
headers={
"Accept": "application/json",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/news/hot?limit=10"))
.header("Accept", "application/json")
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/news/hot?limit=10", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/news/hot?limit=10");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/news/hot?limit=10 HTTP/1.1 Host: boot.qingwu.ink Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": [
{
"id": 4,
"title": "A 股三大指数集体收涨 成交额突破 1.2 万亿",
"summary": "市场情绪回暖，券商、新能源板块领涨，北向资金净流入超 60 亿元。",
"coverImage": null,
"author": "编辑部",
"source": "清吾资讯",
"categoryId": 2,
"categoryName": "财经金融",
"tags": [
"A股",
"股市"
],
"viewCount": 2155,
"likeCount": 143,
"commentCount": 0,
"isTop": 1,
"isHot": 1,
"status": 1,
"publishTime": "2026-10-16 08:54:41",
"favorited": false
}
],
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 array<NewsVO>
| 字段 | 类型 | 说明 |
|---|---|---|
| id | integer | 新闻 ID 例如 1 |
| title | string | 标题 |
| summary | string | 摘要 |
| coverImage | string | 封面图 |
| author | string | 作者 |
| source | string | 来源 |
| categoryId | integer | 分类 ID 例如 3 |
| categoryName | string | 分类名称 例如 科技互联网 |
| tags | array<string> | 标签列表 |
| viewCount | integer | 浏览量 例如 1024 |
| likeCount | integer | 点赞数 例如 58 |
| commentCount | integer | 评论数 例如 12 |
| isTop | integer | 是否置顶：1-是 0-否 |
| isHot | integer | 是否热门：1-是 0-否 |
| status | integer | 状态：0-草稿 1-已发布 2-已下架 |
| publishTime | string | 发布时间 |
| favorited | boolean | 当前登录用户是否已收藏（未登录返回 false） |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 3001 | 新闻不存在或已下架 |
说明
该接口为公开接口，无需任何凭证即可调用。
新闻接口
最新新闻
按发布时间降序返回最新内容，适合资讯流首屏。
接口概要
鉴权要求
公开（无需令牌）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
array<NewsVO>
所属模块
新闻接口
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| limit | integer | 可选 | 返回条数上限 例如 10 |
请求示例7 种语言
该接口无需令牌，可直接调用。把示例中的参数值换成你的实际值即可。
curl -X GET 'https://boot.qingwu.ink/api/v1/news/latest?limit=10' -H 'Accept: application/json'
const res = await fetch('https://boot.qingwu.ink/api/v1/news/latest?limit=10', {
method: 'GET',
headers: {
'Accept': 'application/json',
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/news/latest?limit=10",
headers={
"Accept": "application/json",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/news/latest?limit=10"))
.header("Accept", "application/json")
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/news/latest?limit=10", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/news/latest?limit=10");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/news/latest?limit=10 HTTP/1.1 Host: boot.qingwu.ink Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": [
{
"id": 4,
"title": "A 股三大指数集体收涨 成交额突破 1.2 万亿",
"summary": "市场情绪回暖，券商、新能源板块领涨，北向资金净流入超 60 亿元。",
"coverImage": null,
"author": "编辑部",
"source": "清吾资讯",
"categoryId": 2,
"categoryName": "财经金融",
"tags": [
"A股",
"股市"
],
"viewCount": 2155,
"likeCount": 143,
"commentCount": 0,
"isTop": 1,
"isHot": 1,
"status": 1,
"publishTime": "2026-10-16 08:54:41",
"favorited": false
}
],
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 array<NewsVO>
| 字段 | 类型 | 说明 |
|---|---|---|
| id | integer | 新闻 ID 例如 1 |
| title | string | 标题 |
| summary | string | 摘要 |
| coverImage | string | 封面图 |
| author | string | 作者 |
| source | string | 来源 |
| categoryId | integer | 分类 ID 例如 3 |
| categoryName | string | 分类名称 例如 科技互联网 |
| tags | array<string> | 标签列表 |
| viewCount | integer | 浏览量 例如 1024 |
| likeCount | integer | 点赞数 例如 58 |
| commentCount | integer | 评论数 例如 12 |
| isTop | integer | 是否置顶：1-是 0-否 |
| isHot | integer | 是否热门：1-是 0-否 |
| status | integer | 状态：0-草稿 1-已发布 2-已下架 |
| publishTime | string | 发布时间 |
| favorited | boolean | 当前登录用户是否已收藏（未登录返回 false） |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 3001 | 新闻不存在或已下架 |
说明
该接口为公开接口，无需任何凭证即可调用。
新闻接口
相关新闻
返回同分类下的其他已发布新闻，按浏览量降序，可用于详情页底部推荐。
接口概要
鉴权要求
公开（无需令牌）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
array<NewsVO>
所属模块
新闻接口
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | integer | 必填 | 资源 ID |
| limit | integer | 可选 | 返回条数上限 例如 5 |
请求示例7 种语言
该接口无需令牌，可直接调用。把示例中的参数值换成你的实际值即可。
curl -X GET 'https://boot.qingwu.ink/api/v1/news/1/related?limit=5' -H 'Accept: application/json'
const res = await fetch('https://boot.qingwu.ink/api/v1/news/1/related?limit=5', {
method: 'GET',
headers: {
'Accept': 'application/json',
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/news/1/related?limit=5",
headers={
"Accept": "application/json",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/news/1/related?limit=5"))
.header("Accept", "application/json")
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/news/1/related?limit=5", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/news/1/related?limit=5");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/news/1/related?limit=5 HTTP/1.1 Host: boot.qingwu.ink Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": [
{
"id": 4,
"title": "A 股三大指数集体收涨 成交额突破 1.2 万亿",
"summary": "市场情绪回暖，券商、新能源板块领涨，北向资金净流入超 60 亿元。",
"coverImage": null,
"author": "编辑部",
"source": "清吾资讯",
"categoryId": 2,
"categoryName": "财经金融",
"tags": [
"A股",
"股市"
],
"viewCount": 2155,
"likeCount": 143,
"commentCount": 0,
"isTop": 1,
"isHot": 1,
"status": 1,
"publishTime": "2026-10-16 08:54:41",
"favorited": false
}
],
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 array<NewsVO>
| 字段 | 类型 | 说明 |
|---|---|---|
| id | integer | 新闻 ID 例如 1 |
| title | string | 标题 |
| summary | string | 摘要 |
| coverImage | string | 封面图 |
| author | string | 作者 |
| source | string | 来源 |
| categoryId | integer | 分类 ID 例如 3 |
| categoryName | string | 分类名称 例如 科技互联网 |
| tags | array<string> | 标签列表 |
| viewCount | integer | 浏览量 例如 1024 |
| likeCount | integer | 点赞数 例如 58 |
| commentCount | integer | 评论数 例如 12 |
| isTop | integer | 是否置顶：1-是 0-否 |
| isHot | integer | 是否热门：1-是 0-否 |
| status | integer | 状态：0-草稿 1-已发布 2-已下架 |
| publishTime | string | 发布时间 |
| favorited | boolean | 当前登录用户是否已收藏（未登录返回 false） |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 404 | 路径中的资源 ID 在库中不存在 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 3001 | 新闻不存在或已下架 |
说明
该接口为公开接口，无需任何凭证即可调用。
新闻接口
评论列表
返回树形评论结构：一级评论按时间正序排列，其下的回复挂在 children 中。
接口概要
鉴权要求
公开（无需令牌）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
array<CommentVO>
所属模块
新闻接口
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | integer | 必填 | 资源 ID |
请求示例7 种语言
该接口无需令牌，可直接调用。把示例中的参数值换成你的实际值即可。
curl -X GET 'https://boot.qingwu.ink/api/v1/news/1/comments' -H 'Accept: application/json'
const res = await fetch('https://boot.qingwu.ink/api/v1/news/1/comments', {
method: 'GET',
headers: {
'Accept': 'application/json',
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/news/1/comments",
headers={
"Accept": "application/json",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/news/1/comments"))
.header("Accept", "application/json")
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/news/1/comments", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/news/1/comments");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/news/1/comments HTTP/1.1 Host: boot.qingwu.ink Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": [
{
"id": 1,
"newsId": 4,
"userId": 2,
"nickname": "演示用户",
"avatar": null,
"parentId": 0,
"replyToNickname": null,
"content": "数据比预期更稳健。",
"likeCount": 0,
"createTime": "2026-10-16 09:31:07",
"children": [
{
"id": 2,
"newsId": 4,
"userId": 1,
"nickname": "系统管理员",
"avatar": null,
"parentId": 1,
"replyToNickname": "演示用户",
"content": "同意，后续走势值得持续观察。",
"likeCount": 0,
"createTime": "2026-10-16 09:32:44",
"children": []
}
]
}
],
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 array<CommentVO>
| 字段 | 类型 | 说明 |
|---|---|---|
| id | integer | 评论 ID |
| newsId | integer | 新闻 ID |
| userId | integer | 评论用户 ID |
| nickname | string | 评论用户昵称 |
| avatar | string | 评论用户头像 |
| parentId | integer | 父评论 ID，0 表示一级评论 |
| replyToNickname | string | 被回复用户昵称 |
| content | string | 评论内容 |
| likeCount | integer | 点赞数 |
| createTime | string | 评论时间 |
| children | array<CommentVO> | 子回复列表 |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 404 | 路径中的资源 ID 在库中不存在 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 3001 | 新闻不存在或已下架 |
说明
该接口为公开接口，无需任何凭证即可调用。
新闻接口
发表评论
发表评论或回复。parentId 传 0 为一级评论，传其他评论 ID 即为回复。
接口概要
鉴权要求
需登录（缺少有效令牌返回 401）
请求内容类型
application/json
响应内容类型
application/json
幂等性
非幂等，重复提交会产生多条数据
响应数据模型
CommentVO
所属模块
新闻接口
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | integer | 必填 | 资源 ID |
请求体字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| content | string | 必填 | 评论内容 |
| parentId | integer | 可选 | 父评论 ID，0 表示一级评论 |
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X POST 'https://boot.qingwu.ink/api/v1/news/1/comments'
-H 'Accept: application/json'
-H 'Authorization: Bearer <accessToken>'
-H 'Content-Type: application/json'
-d '{
"content": "数据比预期更稳健。",
"parentId": 0
}'const res = await fetch('https://boot.qingwu.ink/api/v1/news/1/comments', {
method: 'POST',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(payload),
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.post(
"https://boot.qingwu.ink/api/v1/news/1/comments",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {access_token}",
"Content-Type": "application/json",
},
json=payload,
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/news/1/comments"))
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(body))
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("POST", "https://boot.qingwu.ink/api/v1/news/1/comments", strings.NewReader(body))
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer " + accessToken)
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/news/1/comments");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Authorization: Bearer " . $accessToken,
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => $body,
]);
echo curl_exec($ch);
curl_close($ch);POST /api/v1/news/1/comments HTTP/1.1
Host: boot.qingwu.ink
Authorization: Bearer <accessToken>
Accept: application/json
Content-Type: application/json
{
"content": "数据比预期更稳健。",
"parentId": 0
}响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": {
"id": 1,
"newsId": 4,
"userId": 2,
"nickname": "演示用户",
"avatar": null,
"parentId": 0,
"replyToNickname": null,
"content": "数据比预期更稳健。",
"likeCount": 0,
"createTime": "2026-10-16 09:31:07",
"children": [
{
"id": 2,
"newsId": 4,
"userId": 1,
"nickname": "系统管理员",
"avatar": null,
"parentId": 1,
"replyToNickname": "演示用户",
"content": "同意，后续走势值得持续观察。",
"likeCount": 0,
"createTime": "2026-10-16 09:32:44",
"children": []
}
]
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 CommentVO
| 字段 | 类型 | 说明 |
|---|---|---|
| id | integer | 评论 ID |
| newsId | integer | 新闻 ID |
| userId | integer | 评论用户 ID |
| nickname | string | 评论用户昵称 |
| avatar | string | 评论用户头像 |
| parentId | integer | 父评论 ID，0 表示一级评论 |
| replyToNickname | string | 被回复用户昵称 |
| content | string | 评论内容 |
| likeCount | integer | 点赞数 |
| createTime | string | 评论时间 |
| children | array<CommentVO> | 子回复列表 |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 201 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 404 | 路径中的资源 ID 在库中不存在 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 3001 | 新闻不存在或已下架 |
说明
成功时返回 HTTP 201，并同步把新闻的
commentCount 加一。新闻接口
删除评论
删除自己的评论；管理员可删除任意评论。删除一级评论会连带删除其下全部回复。
接口概要
鉴权要求
需登录（缺少有效令牌返回 401）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
基本类型 / 空值
所属模块
新闻接口
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| commentId | integer | 必填 | 评论 ID |
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X DELETE 'https://boot.qingwu.ink/api/v1/news/comments/1' -H 'Accept: application/json' -H 'Authorization: Bearer <accessToken>'
const res = await fetch('https://boot.qingwu.ink/api/v1/news/comments/1', {
method: 'DELETE',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`,
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.delete(
"https://boot.qingwu.ink/api/v1/news/comments/1",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {access_token}",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/news/comments/1"))
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.DELETE()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("DELETE", "https://boot.qingwu.ink/api/v1/news/comments/1", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer " + accessToken)
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/news/comments/1");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "DELETE",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Authorization: Bearer " . $accessToken,
],
]);
echo curl_exec($ch);
curl_close($ch);DELETE /api/v1/news/comments/1 HTTP/1.1 Host: boot.qingwu.ink Authorization: Bearer <accessToken> Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "评论已删除",
"data": null,
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明
该接口的 data 为基本类型或空值，没有可展开的字段。
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 404 | 路径中的资源 ID 在库中不存在 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 3001 | 新闻不存在或已下架 |
说明
删除后会自动回退新闻的
commentCount，不会出现计数漂移。新闻接口
点赞
为新闻点赞，返回递增后的最新点赞数。
接口概要
鉴权要求
需登录（缺少有效令牌返回 401）
请求内容类型
—
响应内容类型
application/json
幂等性
非幂等，重复提交会产生多条数据
响应数据模型
基本类型 / 空值
所属模块
新闻接口
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | integer | 必填 | 资源 ID |
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X POST 'https://boot.qingwu.ink/api/v1/news/1/like' -H 'Accept: application/json' -H 'Authorization: Bearer <accessToken>'
const res = await fetch('https://boot.qingwu.ink/api/v1/news/1/like', {
method: 'POST',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`,
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.post(
"https://boot.qingwu.ink/api/v1/news/1/like",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {access_token}",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/news/1/like"))
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.POST()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("POST", "https://boot.qingwu.ink/api/v1/news/1/like", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer " + accessToken)
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/news/1/like");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Authorization: Bearer " . $accessToken,
],
]);
echo curl_exec($ch);
curl_close($ch);POST /api/v1/news/1/like HTTP/1.1 Host: boot.qingwu.ink Authorization: Bearer <accessToken> Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "点赞成功",
"data": 144,
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明
该接口的 data 为基本类型或空值，没有可展开的字段。
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 404 | 路径中的资源 ID 在库中不存在 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 3001 | 新闻不存在或已下架 |
说明
需在请求头携带
Authorization: Bearer ；令牌过期请先用刷新令牌接口换取新的访问令牌。新闻接口
取消点赞
取消点赞，返回递减后的最新点赞数。计数不会小于 0。
接口概要
鉴权要求
需登录（缺少有效令牌返回 401）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
基本类型 / 空值
所属模块
新闻接口
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | integer | 必填 | 资源 ID |
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X DELETE 'https://boot.qingwu.ink/api/v1/news/1/like' -H 'Accept: application/json' -H 'Authorization: Bearer <accessToken>'
const res = await fetch('https://boot.qingwu.ink/api/v1/news/1/like', {
method: 'DELETE',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`,
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.delete(
"https://boot.qingwu.ink/api/v1/news/1/like",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {access_token}",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/news/1/like"))
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.DELETE()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("DELETE", "https://boot.qingwu.ink/api/v1/news/1/like", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer " + accessToken)
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/news/1/like");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "DELETE",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Authorization: Bearer " . $accessToken,
],
]);
echo curl_exec($ch);
curl_close($ch);DELETE /api/v1/news/1/like HTTP/1.1 Host: boot.qingwu.ink Authorization: Bearer <accessToken> Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "已取消点赞",
"data": 143,
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明
该接口的 data 为基本类型或空值，没有可展开的字段。
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 404 | 路径中的资源 ID 在库中不存在 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 3001 | 新闻不存在或已下架 |
说明
需在请求头携带
Authorization: Bearer ；令牌过期请先用刷新令牌接口换取新的访问令牌。资讯管理
新闻列表（管理端）
与前台列表参数一致，但可额外通过 status 查询草稿与已下架内容。
接口概要
鉴权要求
仅管理员（缺少有效令牌返回 401）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
PageResult<NewsVO>
所属模块
资讯管理
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| pageNum | integer | 可选 | 页码，从 1 开始 例如 1 |
| pageSize | integer | 可选 | 每页条数，最大 100 例如 10 |
| categoryId | integer | 可选 | 新闻分类 ID 例如 3 |
| keyword | string | 可选 | 关键词，模糊匹配 例如 大模型 |
| tag | string | 可选 | 标签，匹配 tags 字段 例如 AI |
| status | integer | 可选 | 状态。用户：1 正常 / 0 禁用；新闻：0 草稿 / 1 已发布 / 2 下架 |
| isHot | integer | 可选 | 是否只查热门：1-是 例如 1 |
| isTop | integer | 可选 | 是否只查置顶：1-是 |
| startTime | string | 可选 | 开始时间（yyyy-MM-dd HH:mm:ss 或 yyyy-MM-dd） |
| endTime | string | 可选 | 结束时间（yyyy-MM-dd HH:mm:ss 或 yyyy-MM-dd） |
| orderBy | string | 可选 | 排序方式：latest 最新 / hot 浏览量 / like 点赞 / comment 评论 例如 latest |
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X GET 'https://boot.qingwu.ink/api/v1/news/manage' -H 'Accept: application/json' -H 'Authorization: Bearer <accessToken>'
const res = await fetch('https://boot.qingwu.ink/api/v1/news/manage', {
method: 'GET',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`,
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/news/manage",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {access_token}",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/news/manage"))
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/news/manage", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer " + accessToken)
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/news/manage");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Authorization: Bearer " . $accessToken,
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/news/manage HTTP/1.1 Host: boot.qingwu.ink Authorization: Bearer <accessToken> Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": {
"pageNum": 1,
"pageSize": 5,
"total": 25,
"pages": 5,
"list": [
{
"id": 4,
"title": "A 股三大指数集体收涨 成交额突破 1.2 万亿",
"summary": "市场情绪回暖，券商、新能源板块领涨，北向资金净流入超 60 亿元。",
"coverImage": null,
"author": "编辑部",
"source": "清吾资讯",
"categoryId": 2,
"categoryName": "财经金融",
"tags": [
"A股",
"股市"
],
"viewCount": 2155,
"likeCount": 143,
"commentCount": 0,
"isTop": 1,
"isHot": 1,
"status": 1,
"publishTime": "2026-10-16 08:54:41",
"favorited": false
}
]
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 PageResult<NewsVO>
| 字段 | 类型 | 说明 |
|---|---|---|
| pageNum | integer | 当前页码 |
| pageSize | integer | 每页条数 |
| total | integer | 记录总数 |
| pages | integer | 总页数 |
| list | array<NewsVO> | 当前页的数据集合 |
| list.id | integer | 新闻 ID 例如 1 |
| list.title | string | 标题 |
| list.summary | string | 摘要 |
| list.coverImage | string | 封面图 |
| list.author | string | 作者 |
| list.source | string | 来源 |
| list.categoryId | integer | 分类 ID 例如 3 |
| list.categoryName | string | 分类名称 例如 科技互联网 |
| list.tags | array<string> | 标签列表 |
| list.viewCount | integer | 浏览量 例如 1024 |
| list.likeCount | integer | 点赞数 例如 58 |
| list.commentCount | integer | 评论数 例如 12 |
| list.isTop | integer | 是否置顶：1-是 0-否 |
| list.isHot | integer | 是否热门：1-是 0-否 |
| list.status | integer | 状态：0-草稿 1-已发布 2-已下架 |
| list.publishTime | string | 发布时间 |
| list.favorited | boolean | 当前登录用户是否已收藏（未登录返回 false） |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 403 | 已登录但不是管理员；或账号被禁用 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 3001 | 新闻不存在或已下架 |
说明
本组接口需要管理员角色，普通用户访问会返回 403。
分页从第 1 页开始，
pageSize 上限 100、超出会被下取；total 是满足条件的记录总数，与当前页长度无关。该接口要求管理员角色：普通用户即使携带有效令牌也会被拒绝（HTTP 403，业务码
1011）。资讯管理
新增新闻
创建一条新闻。状态为已发布且未指定发布时间时，自动填入当前时间。
接口概要
鉴权要求
仅管理员（缺少有效令牌返回 401）
请求内容类型
application/json
响应内容类型
application/json
幂等性
非幂等，重复提交会产生多条数据
响应数据模型
NewsVO
所属模块
资讯管理
请求体字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| title | string | 必填 | 标题 |
| summary | string | 可选 | 摘要 |
| content | string | 可选 | 正文内容 |
| coverImage | string | 可选 | 封面图 |
| author | string | 可选 | 作者 |
| source | string | 可选 | 来源 |
| categoryId | integer | 必填 | 分类 ID |
| tags | string | 可选 | 标签，英文逗号分隔 |
| isTop | integer | 可选 | 是否置顶：1-是 0-否 |
| isHot | integer | 可选 | 是否热门：1-是 0-否 |
| status | integer | 可选 | 状态：0-草稿 1-已发布 2-已下架 |
| publishTime | string | 可选 | 发布时间，不传则取当前时间 |
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X POST 'https://boot.qingwu.ink/api/v1/news'
-H 'Accept: application/json'
-H 'Authorization: Bearer <accessToken>'
-H 'Content-Type: application/json'
-d '{
"title": "国产大模型迎来新一轮技术迭代",
"summary": "多家厂商发布新一代大模型，推理能力与多模态理解显著提升。",
"content": "<p>正文内容……</p>",
"categoryId": 3,
"tags": "AI,大模型",
"author": "编辑部",
"source": "清吾资讯",
"isHot": 1,
"isTop": 0,
"status": 1
}'const res = await fetch('https://boot.qingwu.ink/api/v1/news', {
method: 'POST',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(payload),
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.post(
"https://boot.qingwu.ink/api/v1/news",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {access_token}",
"Content-Type": "application/json",
},
json=payload,
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/news"))
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(body))
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("POST", "https://boot.qingwu.ink/api/v1/news", strings.NewReader(body))
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer " + accessToken)
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/news");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Authorization: Bearer " . $accessToken,
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => $body,
]);
echo curl_exec($ch);
curl_close($ch);POST /api/v1/news HTTP/1.1
Host: boot.qingwu.ink
Authorization: Bearer <accessToken>
Accept: application/json
Content-Type: application/json
{
"title": "国产大模型迎来新一轮技术迭代",
"summary": "多家厂商发布新一代大模型，推理能力与多模态理解显著提升。",
"content": "<p>正文内容……</p>",
"categoryId": 3,
"tags": "AI,大模型",
"author": "编辑部",
"source": "清吾资讯",
"isHot": 1,
"isTop": 0,
"status": 1
}响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": {
"id": 4,
"title": "A 股三大指数集体收涨 成交额突破 1.2 万亿",
"summary": "市场情绪回暖，券商、新能源板块领涨，北向资金净流入超 60 亿元。",
"coverImage": null,
"author": "编辑部",
"source": "清吾资讯",
"categoryId": 2,
"categoryName": "财经金融",
"tags": [
"A股",
"股市"
],
"viewCount": 2155,
"likeCount": 143,
"commentCount": 0,
"isTop": 1,
"isHot": 1,
"status": 1,
"publishTime": "2026-10-16 08:54:41",
"favorited": false
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 NewsVO
| 字段 | 类型 | 说明 |
|---|---|---|
| id | integer | 新闻 ID 例如 1 |
| title | string | 标题 |
| summary | string | 摘要 |
| coverImage | string | 封面图 |
| author | string | 作者 |
| source | string | 来源 |
| categoryId | integer | 分类 ID 例如 3 |
| categoryName | string | 分类名称 例如 科技互联网 |
| tags | array<string> | 标签列表 |
| viewCount | integer | 浏览量 例如 1024 |
| likeCount | integer | 点赞数 例如 58 |
| commentCount | integer | 评论数 例如 12 |
| isTop | integer | 是否置顶：1-是 0-否 |
| isHot | integer | 是否热门：1-是 0-否 |
| status | integer | 状态：0-草稿 1-已发布 2-已下架 |
| publishTime | string | 发布时间 |
| favorited | boolean | 当前登录用户是否已收藏（未登录返回 false） |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 201 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 403 | 已登录但不是管理员；或账号被禁用 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 3001 | 新闻不存在或已下架 |
说明
本组接口需要管理员角色，普通用户访问会返回 403。
分类不存在返回
3002。status 取值为 0 草稿、1 已发布、2 已下架。资讯管理
编辑新闻
全量更新新闻字段，常用于后台编辑器保存。
接口概要
鉴权要求
仅管理员（缺少有效令牌返回 401）
请求内容类型
application/json
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
NewsVO
所属模块
资讯管理
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | integer | 必填 | 资源 ID |
请求体字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| title | string | 必填 | 标题 |
| summary | string | 可选 | 摘要 |
| content | string | 可选 | 正文内容 |
| coverImage | string | 可选 | 封面图 |
| author | string | 可选 | 作者 |
| source | string | 可选 | 来源 |
| categoryId | integer | 必填 | 分类 ID |
| tags | string | 可选 | 标签，英文逗号分隔 |
| isTop | integer | 可选 | 是否置顶：1-是 0-否 |
| isHot | integer | 可选 | 是否热门：1-是 0-否 |
| status | integer | 可选 | 状态：0-草稿 1-已发布 2-已下架 |
| publishTime | string | 可选 | 发布时间，不传则取当前时间 |
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X PUT 'https://boot.qingwu.ink/api/v1/news/1'
-H 'Accept: application/json'
-H 'Authorization: Bearer <accessToken>'
-H 'Content-Type: application/json'
-d '{
"title": "string",
"summary": "string",
"content": "string",
"coverImage": "string",
"author": "string",
"source": "string",
"categoryId": 1,
"tags": "string",
"isTop": 1,
"isHot": 1,
"status": 1,
"publishTime": "string"
}'const res = await fetch('https://boot.qingwu.ink/api/v1/news/1', {
method: 'PUT',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(payload),
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.put(
"https://boot.qingwu.ink/api/v1/news/1",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {access_token}",
"Content-Type": "application/json",
},
json=payload,
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/news/1"))
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.header("Content-Type", "application/json")
.PUT(HttpRequest.BodyPublishers.ofString(body))
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("PUT", "https://boot.qingwu.ink/api/v1/news/1", strings.NewReader(body))
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer " + accessToken)
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/news/1");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Authorization: Bearer " . $accessToken,
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => $body,
]);
echo curl_exec($ch);
curl_close($ch);PUT /api/v1/news/1 HTTP/1.1
Host: boot.qingwu.ink
Authorization: Bearer <accessToken>
Accept: application/json
Content-Type: application/json
{
"title": "string",
"summary": "string",
"content": "string",
"coverImage": "string",
"author": "string",
"source": "string",
"categoryId": 1,
"tags": "string",
"isTop": 1,
"isHot": 1,
"status": 1,
"publishTime": "string"
}响应示例
200 OK
{
"code": 200,
"message": "新闻已更新",
"data": {
"id": 4,
"title": "A 股三大指数集体收涨 成交额突破 1.2 万亿",
"summary": "市场情绪回暖，券商、新能源板块领涨，北向资金净流入超 60 亿元。",
"coverImage": null,
"author": "编辑部",
"source": "清吾资讯",
"categoryId": 2,
"categoryName": "财经金融",
"tags": [
"A股",
"股市"
],
"viewCount": 2155,
"likeCount": 143,
"commentCount": 0,
"isTop": 1,
"isHot": 1,
"status": 1,
"publishTime": "2026-10-16 08:54:41",
"favorited": false
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 NewsVO
| 字段 | 类型 | 说明 |
|---|---|---|
| id | integer | 新闻 ID 例如 1 |
| title | string | 标题 |
| summary | string | 摘要 |
| coverImage | string | 封面图 |
| author | string | 作者 |
| source | string | 来源 |
| categoryId | integer | 分类 ID 例如 3 |
| categoryName | string | 分类名称 例如 科技互联网 |
| tags | array<string> | 标签列表 |
| viewCount | integer | 浏览量 例如 1024 |
| likeCount | integer | 点赞数 例如 58 |
| commentCount | integer | 评论数 例如 12 |
| isTop | integer | 是否置顶：1-是 0-否 |
| isHot | integer | 是否热门：1-是 0-否 |
| status | integer | 状态：0-草稿 1-已发布 2-已下架 |
| publishTime | string | 发布时间 |
| favorited | boolean | 当前登录用户是否已收藏（未登录返回 false） |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 403 | 已登录但不是管理员；或账号被禁用 |
| 404 | 路径中的资源 ID 在库中不存在 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 3001 | 新闻不存在或已下架 |
说明
本组接口需要管理员角色，普通用户访问会返回 403。
字段校验在进入业务逻辑之前完成，未通过时
message 会聚合全部字段的错误提示。该接口要求管理员角色：普通用户即使携带有效令牌也会被拒绝（HTTP 403，业务码
1011）。资讯管理
修改新闻状态
在草稿、已发布、已下架之间切换，无需提交完整正文即可上下架。
接口概要
鉴权要求
仅管理员（缺少有效令牌返回 401）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
NewsVO
所属模块
资讯管理
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | integer | 必填 | 资源 ID |
| status | integer | 必填 | 状态。用户：1 正常 / 0 禁用；新闻：0 草稿 / 1 已发布 / 2 下架 |
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X PUT 'https://boot.qingwu.ink/api/v1/news/1/status?status=1' -H 'Accept: application/json' -H 'Authorization: Bearer <accessToken>'
const res = await fetch('https://boot.qingwu.ink/api/v1/news/1/status?status=1', {
method: 'PUT',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`,
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.put(
"https://boot.qingwu.ink/api/v1/news/1/status?status=1",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {access_token}",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/news/1/status?status=1"))
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.PUT()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("PUT", "https://boot.qingwu.ink/api/v1/news/1/status?status=1", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer " + accessToken)
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/news/1/status?status=1");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Authorization: Bearer " . $accessToken,
],
]);
echo curl_exec($ch);
curl_close($ch);PUT /api/v1/news/1/status?status=1 HTTP/1.1 Host: boot.qingwu.ink Authorization: Bearer <accessToken> Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "状态已更新",
"data": {
"id": 4,
"title": "A 股三大指数集体收涨 成交额突破 1.2 万亿",
"summary": "市场情绪回暖，券商、新能源板块领涨，北向资金净流入超 60 亿元。",
"coverImage": null,
"author": "编辑部",
"source": "清吾资讯",
"categoryId": 2,
"categoryName": "财经金融",
"tags": [
"A股",
"股市"
],
"viewCount": 2155,
"likeCount": 143,
"commentCount": 0,
"isTop": 1,
"isHot": 1,
"status": 1,
"publishTime": "2026-10-16 08:54:41",
"favorited": false
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 NewsVO
| 字段 | 类型 | 说明 |
|---|---|---|
| id | integer | 新闻 ID 例如 1 |
| title | string | 标题 |
| summary | string | 摘要 |
| coverImage | string | 封面图 |
| author | string | 作者 |
| source | string | 来源 |
| categoryId | integer | 分类 ID 例如 3 |
| categoryName | string | 分类名称 例如 科技互联网 |
| tags | array<string> | 标签列表 |
| viewCount | integer | 浏览量 例如 1024 |
| likeCount | integer | 点赞数 例如 58 |
| commentCount | integer | 评论数 例如 12 |
| isTop | integer | 是否置顶：1-是 0-否 |
| isHot | integer | 是否热门：1-是 0-否 |
| status | integer | 状态：0-草稿 1-已发布 2-已下架 |
| publishTime | string | 发布时间 |
| favorited | boolean | 当前登录用户是否已收藏（未登录返回 false） |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 403 | 已登录但不是管理员；或账号被禁用 |
| 404 | 路径中的资源 ID 在库中不存在 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 3001 | 新闻不存在或已下架 |
说明
本组接口需要管理员角色，普通用户访问会返回 403。
该接口要求管理员角色：普通用户即使携带有效令牌也会被拒绝（HTTP 403，业务码
1011）。资讯管理
删除新闻
逻辑删除，数据仍保留在库中，前台与列表接口均不再返回。
接口概要
鉴权要求
仅管理员（缺少有效令牌返回 401）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
基本类型 / 空值
所属模块
资讯管理
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | integer | 必填 | 资源 ID |
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X DELETE 'https://boot.qingwu.ink/api/v1/news/1' -H 'Accept: application/json' -H 'Authorization: Bearer <accessToken>'
const res = await fetch('https://boot.qingwu.ink/api/v1/news/1', {
method: 'DELETE',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`,
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.delete(
"https://boot.qingwu.ink/api/v1/news/1",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {access_token}",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/news/1"))
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.DELETE()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("DELETE", "https://boot.qingwu.ink/api/v1/news/1", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer " + accessToken)
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/news/1");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "DELETE",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Authorization: Bearer " . $accessToken,
],
]);
echo curl_exec($ch);
curl_close($ch);DELETE /api/v1/news/1 HTTP/1.1 Host: boot.qingwu.ink Authorization: Bearer <accessToken> Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "新闻已删除",
"data": null,
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明
该接口的 data 为基本类型或空值，没有可展开的字段。
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 403 | 已登录但不是管理员；或账号被禁用 |
| 404 | 路径中的资源 ID 在库中不存在 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 3001 | 新闻不存在或已下架 |
说明
本组接口需要管理员角色，普通用户访问会返回 403。
该接口要求管理员角色：普通用户即使携带有效令牌也会被拒绝（HTTP 403，业务码
1011）。新闻分类
分类列表
默认只返回启用中的分类；传 all=true 可获取全部（含停用），用于后台管理页。
接口概要
鉴权要求
公开（无需令牌）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
array<NewsCategory>
所属模块
新闻分类
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| all | boolean | 可选 | 是否包含已停用的数据，默认 false 例如 False |
请求示例7 种语言
该接口无需令牌，可直接调用。把示例中的参数值换成你的实际值即可。
curl -X GET 'https://boot.qingwu.ink/api/v1/categories?all=False' -H 'Accept: application/json'
const res = await fetch('https://boot.qingwu.ink/api/v1/categories?all=False', {
method: 'GET',
headers: {
'Accept': 'application/json',
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/categories?all=False",
headers={
"Accept": "application/json",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/categories?all=False"))
.header("Accept", "application/json")
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/categories?all=False", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/categories?all=False");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/categories?all=False HTTP/1.1 Host: boot.qingwu.ink Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": [
{
"id": 3,
"name": "科技互联网",
"code": "tech",
"icon": null,
"description": "科技前沿与互联网动态",
"sort": 3,
"status": 1,
"createTime": "2026-10-16 08:59:41",
"updateTime": "2026-10-16 08:59:41"
}
],
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 array<NewsCategory>
| 字段 | 类型 | 说明 |
|---|---|---|
| createTime | string | 创建时间 |
| updateTime | string | 更新时间 |
| id | integer | 分类 ID 例如 1 |
| name | string | 分类名称 例如 科技互联网 |
| code | string | 分类编码 例如 tech |
| icon | string | 分类图标 |
| description | string | 分类描述 |
| sort | integer | 排序值 例如 1 |
| status | integer | 状态：1-启用 0-停用 例如 1 |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 3002 | 新闻分类不存在 |
| 3003 | 分类名称已存在 |
| 3004 | 该分类下仍有新闻，无法删除 |
说明
该接口为公开接口，无需任何凭证即可调用。
新闻分类
分类详情
按 ID 查询单个分类。
接口概要
鉴权要求
公开（无需令牌）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
NewsCategory
所属模块
新闻分类
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | integer | 必填 | 资源 ID |
请求示例7 种语言
该接口无需令牌，可直接调用。把示例中的参数值换成你的实际值即可。
curl -X GET 'https://boot.qingwu.ink/api/v1/categories/1' -H 'Accept: application/json'
const res = await fetch('https://boot.qingwu.ink/api/v1/categories/1', {
method: 'GET',
headers: {
'Accept': 'application/json',
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/categories/1",
headers={
"Accept": "application/json",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/categories/1"))
.header("Accept", "application/json")
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/categories/1", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/categories/1");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/categories/1 HTTP/1.1 Host: boot.qingwu.ink Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": {
"id": 3,
"name": "科技互联网",
"code": "tech",
"icon": null,
"description": "科技前沿与互联网动态",
"sort": 3,
"status": 1,
"createTime": "2026-10-16 08:59:41",
"updateTime": "2026-10-16 08:59:41"
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 NewsCategory
| 字段 | 类型 | 说明 |
|---|---|---|
| createTime | string | 创建时间 |
| updateTime | string | 更新时间 |
| id | integer | 分类 ID 例如 1 |
| name | string | 分类名称 例如 科技互联网 |
| code | string | 分类编码 例如 tech |
| icon | string | 分类图标 |
| description | string | 分类描述 |
| sort | integer | 排序值 例如 1 |
| status | integer | 状态：1-启用 0-停用 例如 1 |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 404 | 路径中的资源 ID 在库中不存在 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 3002 | 新闻分类不存在 |
| 3003 | 分类名称已存在 |
| 3004 | 该分类下仍有新闻，无法删除 |
说明
分类不存在时返回
3002 与 HTTP 404。新闻分类
按分类查新闻
等价于在新闻列表中固定 categoryId，其余筛选与分页参数完全一致。
接口概要
鉴权要求
公开（无需令牌）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
PageResult<NewsVO>
所属模块
新闻分类
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | integer | 必填 | 资源 ID |
| pageNum | integer | 可选 | 页码，从 1 开始 例如 1 |
| pageSize | integer | 可选 | 每页条数，最大 100 例如 10 |
| categoryId | integer | 可选 | 新闻分类 ID 例如 3 |
| keyword | string | 可选 | 关键词，模糊匹配 例如 大模型 |
| tag | string | 可选 | 标签，匹配 tags 字段 例如 AI |
| status | integer | 可选 | 状态。用户：1 正常 / 0 禁用；新闻：0 草稿 / 1 已发布 / 2 下架 |
| isHot | integer | 可选 | 是否只查热门：1-是 例如 1 |
| isTop | integer | 可选 | 是否只查置顶：1-是 |
| startTime | string | 可选 | 开始时间（yyyy-MM-dd HH:mm:ss 或 yyyy-MM-dd） |
| endTime | string | 可选 | 结束时间（yyyy-MM-dd HH:mm:ss 或 yyyy-MM-dd） |
| orderBy | string | 可选 | 排序方式：latest 最新 / hot 浏览量 / like 点赞 / comment 评论 例如 latest |
请求示例7 种语言
该接口无需令牌，可直接调用。把示例中的参数值换成你的实际值即可。
curl -X GET 'https://boot.qingwu.ink/api/v1/categories/1/news' -H 'Accept: application/json'
const res = await fetch('https://boot.qingwu.ink/api/v1/categories/1/news', {
method: 'GET',
headers: {
'Accept': 'application/json',
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/categories/1/news",
headers={
"Accept": "application/json",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/categories/1/news"))
.header("Accept", "application/json")
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/categories/1/news", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/categories/1/news");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/categories/1/news HTTP/1.1 Host: boot.qingwu.ink Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": {
"pageNum": 1,
"pageSize": 5,
"total": 5,
"pages": 1,
"list": [
{
"id": 4,
"title": "A 股三大指数集体收涨 成交额突破 1.2 万亿",
"summary": "市场情绪回暖，券商、新能源板块领涨，北向资金净流入超 60 亿元。",
"coverImage": null,
"author": "编辑部",
"source": "清吾资讯",
"categoryId": 2,
"categoryName": "财经金融",
"tags": [
"A股",
"股市"
],
"viewCount": 2155,
"likeCount": 143,
"commentCount": 0,
"isTop": 1,
"isHot": 1,
"status": 1,
"publishTime": "2026-10-16 08:54:41",
"favorited": false
}
]
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 PageResult<NewsVO>
| 字段 | 类型 | 说明 |
|---|---|---|
| pageNum | integer | 当前页码 |
| pageSize | integer | 每页条数 |
| total | integer | 记录总数 |
| pages | integer | 总页数 |
| list | array<NewsVO> | 当前页的数据集合 |
| list.id | integer | 新闻 ID 例如 1 |
| list.title | string | 标题 |
| list.summary | string | 摘要 |
| list.coverImage | string | 封面图 |
| list.author | string | 作者 |
| list.source | string | 来源 |
| list.categoryId | integer | 分类 ID 例如 3 |
| list.categoryName | string | 分类名称 例如 科技互联网 |
| list.tags | array<string> | 标签列表 |
| list.viewCount | integer | 浏览量 例如 1024 |
| list.likeCount | integer | 点赞数 例如 58 |
| list.commentCount | integer | 评论数 例如 12 |
| list.isTop | integer | 是否置顶：1-是 0-否 |
| list.isHot | integer | 是否热门：1-是 0-否 |
| list.status | integer | 状态：0-草稿 1-已发布 2-已下架 |
| list.publishTime | string | 发布时间 |
| list.favorited | boolean | 当前登录用户是否已收藏（未登录返回 false） |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 404 | 路径中的资源 ID 在库中不存在 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 3002 | 新闻分类不存在 |
| 3003 | 分类名称已存在 |
| 3004 | 该分类下仍有新闻，无法删除 |
说明
分页从第 1 页开始，
pageSize 上限 100、超出会被下取；total 是满足条件的记录总数，与当前页长度无关。新闻分类
新增分类
创建新闻分类。名称需唯一，重名返回 3003。
接口概要
鉴权要求
仅管理员（缺少有效令牌返回 401）
请求内容类型
application/json
响应内容类型
application/json
幂等性
非幂等，重复提交会产生多条数据
响应数据模型
NewsCategory
所属模块
新闻分类
请求体字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | string | 必填 | 分类名称 例如 科技互联网 |
| code | string | 可选 | 分类编码 例如 tech |
| icon | string | 可选 | 分类图标 URL |
| description | string | 可选 | 分类描述 |
| sort | integer | 可选 | 排序值，越小越靠前 例如 1 |
| status | integer | 可选 | 状态：1-启用 0-停用 例如 1 |
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X POST 'https://boot.qingwu.ink/api/v1/categories'
-H 'Accept: application/json'
-H 'Authorization: Bearer <accessToken>'
-H 'Content-Type: application/json'
-d '{
"name": "科技互联网",
"code": "tech",
"description": "科技前沿与互联网动态",
"sort": 3,
"status": 1
}'const res = await fetch('https://boot.qingwu.ink/api/v1/categories', {
method: 'POST',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(payload),
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.post(
"https://boot.qingwu.ink/api/v1/categories",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {access_token}",
"Content-Type": "application/json",
},
json=payload,
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/categories"))
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(body))
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("POST", "https://boot.qingwu.ink/api/v1/categories", strings.NewReader(body))
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer " + accessToken)
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/categories");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Authorization: Bearer " . $accessToken,
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => $body,
]);
echo curl_exec($ch);
curl_close($ch);POST /api/v1/categories HTTP/1.1
Host: boot.qingwu.ink
Authorization: Bearer <accessToken>
Accept: application/json
Content-Type: application/json
{
"name": "科技互联网",
"code": "tech",
"description": "科技前沿与互联网动态",
"sort": 3,
"status": 1
}响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": {
"id": 3,
"name": "科技互联网",
"code": "tech",
"icon": null,
"description": "科技前沿与互联网动态",
"sort": 3,
"status": 1,
"createTime": "2026-10-16 08:59:41",
"updateTime": "2026-10-16 08:59:41"
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 NewsCategory
| 字段 | 类型 | 说明 |
|---|---|---|
| createTime | string | 创建时间 |
| updateTime | string | 更新时间 |
| id | integer | 分类 ID 例如 1 |
| name | string | 分类名称 例如 科技互联网 |
| code | string | 分类编码 例如 tech |
| icon | string | 分类图标 |
| description | string | 分类描述 |
| sort | integer | 排序值 例如 1 |
| status | integer | 状态：1-启用 0-停用 例如 1 |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 201 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 403 | 已登录但不是管理员；或账号被禁用 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 3002 | 新闻分类不存在 |
| 3003 | 分类名称已存在 |
| 3004 | 该分类下仍有新闻，无法删除 |
说明
字段校验在进入业务逻辑之前完成，未通过时
message 会聚合全部字段的错误提示。该接口要求管理员角色：普通用户即使携带有效令牌也会被拒绝（HTTP 403，业务码
1011）。新闻分类
修改分类
更新分类名称、编码、描述、排序与启用状态。
接口概要
鉴权要求
仅管理员（缺少有效令牌返回 401）
请求内容类型
application/json
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
NewsCategory
所属模块
新闻分类
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | integer | 必填 | 资源 ID |
请求体字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | string | 必填 | 分类名称 例如 科技互联网 |
| code | string | 可选 | 分类编码 例如 tech |
| icon | string | 可选 | 分类图标 URL |
| description | string | 可选 | 分类描述 |
| sort | integer | 可选 | 排序值，越小越靠前 例如 1 |
| status | integer | 可选 | 状态：1-启用 0-停用 例如 1 |
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X PUT 'https://boot.qingwu.ink/api/v1/categories/1'
-H 'Accept: application/json'
-H 'Authorization: Bearer <accessToken>'
-H 'Content-Type: application/json'
-d '{
"name": "科技互联网",
"code": "tech",
"icon": "string",
"description": "string",
"sort": 1,
"status": 1
}'const res = await fetch('https://boot.qingwu.ink/api/v1/categories/1', {
method: 'PUT',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(payload),
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.put(
"https://boot.qingwu.ink/api/v1/categories/1",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {access_token}",
"Content-Type": "application/json",
},
json=payload,
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/categories/1"))
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.header("Content-Type", "application/json")
.PUT(HttpRequest.BodyPublishers.ofString(body))
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("PUT", "https://boot.qingwu.ink/api/v1/categories/1", strings.NewReader(body))
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer " + accessToken)
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/categories/1");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Authorization: Bearer " . $accessToken,
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => $body,
]);
echo curl_exec($ch);
curl_close($ch);PUT /api/v1/categories/1 HTTP/1.1
Host: boot.qingwu.ink
Authorization: Bearer <accessToken>
Accept: application/json
Content-Type: application/json
{
"name": "科技互联网",
"code": "tech",
"icon": "string",
"description": "string",
"sort": 1,
"status": 1
}响应示例
200 OK
{
"code": 200,
"message": "分类已更新",
"data": {
"id": 3,
"name": "科技互联网",
"code": "tech",
"icon": null,
"description": "科技前沿与互联网动态",
"sort": 3,
"status": 1,
"createTime": "2026-10-16 08:59:41",
"updateTime": "2026-10-16 08:59:41"
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 NewsCategory
| 字段 | 类型 | 说明 |
|---|---|---|
| createTime | string | 创建时间 |
| updateTime | string | 更新时间 |
| id | integer | 分类 ID 例如 1 |
| name | string | 分类名称 例如 科技互联网 |
| code | string | 分类编码 例如 tech |
| icon | string | 分类图标 |
| description | string | 分类描述 |
| sort | integer | 排序值 例如 1 |
| status | integer | 状态：1-启用 0-停用 例如 1 |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 403 | 已登录但不是管理员；或账号被禁用 |
| 404 | 路径中的资源 ID 在库中不存在 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 3002 | 新闻分类不存在 |
| 3003 | 分类名称已存在 |
| 3004 | 该分类下仍有新闻，无法删除 |
说明
字段校验在进入业务逻辑之前完成，未通过时
message 会聚合全部字段的错误提示。该接口要求管理员角色：普通用户即使携带有效令牌也会被拒绝（HTTP 403，业务码
1011）。新闻分类
删除分类
逻辑删除分类。若分类下仍有关联新闻，会被拒绝并提示剩余数量。
接口概要
鉴权要求
仅管理员（缺少有效令牌返回 401）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
基本类型 / 空值
所属模块
新闻分类
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | integer | 必填 | 资源 ID |
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X DELETE 'https://boot.qingwu.ink/api/v1/categories/1' -H 'Accept: application/json' -H 'Authorization: Bearer <accessToken>'
const res = await fetch('https://boot.qingwu.ink/api/v1/categories/1', {
method: 'DELETE',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`,
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.delete(
"https://boot.qingwu.ink/api/v1/categories/1",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {access_token}",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/categories/1"))
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.DELETE()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("DELETE", "https://boot.qingwu.ink/api/v1/categories/1", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer " + accessToken)
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/categories/1");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "DELETE",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Authorization: Bearer " . $accessToken,
],
]);
echo curl_exec($ch);
curl_close($ch);DELETE /api/v1/categories/1 HTTP/1.1 Host: boot.qingwu.ink Authorization: Bearer <accessToken> Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "分类已删除",
"data": null,
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明
该接口的 data 为基本类型或空值，没有可展开的字段。
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 403 | 已登录但不是管理员；或账号被禁用 |
| 404 | 路径中的资源 ID 在库中不存在 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 3002 | 新闻分类不存在 |
| 3003 | 分类名称已存在 |
| 3004 | 该分类下仍有新闻，无法删除 |
说明
分类下存在新闻时返回
3004 与 HTTP 409，请先迁移或删除这些新闻。天气预报
查询城市天气
一次拿到今日实况与未来若干日预报。城市可用 ID 或名称指定，名称支持简写与拼音。
接口概要
鉴权要求
公开（无需令牌）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
WeatherVO
所属模块
天气预报
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| cityId | integer | 可选 | 城市 ID，如 440300 |
| city | string | 可选 | 城市名称，支持「北京」「深圳市」「beijing」等写法 |
| forecastDays | integer | 可选 | 预报天数，1–15，默认 7 |
请求示例7 种语言
该接口无需令牌，可直接调用。把示例中的参数值换成你的实际值即可。
curl -X GET 'https://boot.qingwu.ink/api/v1/weather?cityId=1&forecastDays=1' -H 'Accept: application/json'
const res = await fetch('https://boot.qingwu.ink/api/v1/weather?cityId=1&forecastDays=1', {
method: 'GET',
headers: {
'Accept': 'application/json',
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/weather?cityId=1&forecastDays=1",
headers={
"Accept": "application/json",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/weather?cityId=1&forecastDays=1"))
.header("Accept", "application/json")
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/weather?cityId=1&forecastDays=1", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/weather?cityId=1&forecastDays=1");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/weather?cityId=1&forecastDays=1 HTTP/1.1 Host: boot.qingwu.ink Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": {
"cityId": 440300,
"cityName": "深圳市",
"provinceName": "广东省",
"dataSource": "MOCK",
"updateTime": "2026-10-16 09:24:02",
"current": {
"date": "2026-10-16",
"week": "星期五",
"weatherDay": "雷阵雨",
"weatherNight": "晴",
"tempHigh": 22,
"tempLow": 11,
"tempCurrent": 21,
"humidity": 85,
"windDirection": "东北风",
"windScale": "5级",
"aqi": 60,
"airQuality": "良",
"precipitation": 5.24,
"sunrise": "06:28",
"sunset": "18:02",
"tip": "有雷阵雨，注意防雷，尽量减少户外活动"
},
"forecast": [
{
"date": "2026-10-17",
"week": "星期六",
"weatherDay": "阴",
"weatherNight": "阴",
"tempHigh": 21,
"tempLow": 10,
"tempCurrent": null,
"humidity": 45,
"windDirection": "东风",
"windScale": "2级",
"aqi": 125,
"airQuality": "轻度污染",
"precipitation": 0.0,
"sunrise": "06:29",
"sunset": "18:01",
"tip": "天气舒适，适宜户外活动"
}
]
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 WeatherVO
| 字段 | 类型 | 说明 |
|---|---|---|
| cityId | integer | 城市 ID 例如 110100 |
| cityName | string | 城市名称 例如 北京市 |
| provinceName | string | 省份名称 例如 北京市 |
| dataSource | string | 数据来源：MOCK-模拟数据 REAL-真实数据 例如 MOCK |
| updateTime | string | 更新时间 |
| current | Item | — |
| current.date | string | 日期 例如 2026-10-16 |
| current.week | string | 星期 例如 星期五 |
| current.weatherDay | string | 白天天气 例如 晴 |
| current.weatherNight | string | 夜间天气 例如 多云 |
| current.tempHigh | integer | 最高气温 ℃ 例如 24 |
| current.tempLow | integer | 最低气温 ℃ 例如 14 |
| current.tempCurrent | integer | 当前气温 ℃（仅当天有效） 例如 21 |
| current.humidity | integer | 相对湿度 % 例如 48 |
| current.windDirection | string | 风向 例如 西北风 |
| current.windScale | string | 风力等级 例如 3级 |
| current.aqi | integer | 空气质量指数 例如 62 |
| current.airQuality | string | 空气质量等级 例如 良 |
| current.precipitation | number | 降水量 mm 例如 0.0 |
| current.sunrise | string | 日出时间 例如 06:12 |
| current.sunset | string | 日落时间 例如 17:48 |
| current.tip | string | 生活提示 |
| forecast | array<Item> | 未来天气预报 |
| forecast.date | string | 日期 例如 2026-10-16 |
| forecast.week | string | 星期 例如 星期五 |
| forecast.weatherDay | string | 白天天气 例如 晴 |
| forecast.weatherNight | string | 夜间天气 例如 多云 |
| forecast.tempHigh | integer | 最高气温 ℃ 例如 24 |
| forecast.tempLow | integer | 最低气温 ℃ 例如 14 |
| forecast.tempCurrent | integer | 当前气温 ℃（仅当天有效） 例如 21 |
| forecast.humidity | integer | 相对湿度 % 例如 48 |
| forecast.windDirection | string | 风向 例如 西北风 |
| forecast.windScale | string | 风力等级 例如 3级 |
| forecast.aqi | integer | 空气质量指数 例如 62 |
| forecast.airQuality | string | 空气质量等级 例如 良 |
| forecast.precipitation | number | 降水量 mm 例如 0.0 |
| forecast.sunrise | string | 日出时间 例如 06:12 |
| forecast.sunset | string | 日落时间 例如 17:48 |
| forecast.tip | string | 生活提示 |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 4001 | 暂无该城市的天气数据 |
| 4002 | 请指定城市名称或城市 ID |
说明
cityId 与 city 传其一即可，同时传入时以 cityId 为准；两者都缺返回 4002。直辖市与特别行政区直接以省级本身作为查询城市，因此
city=北京 得到 cityName = 北京市。数据来源为
MOCK。接入真实气象服务时替换服务层实现即可，调用方无需改动。天气预报
今日实况
只取今天的天气实况，响应体更小，适合卡片式展示。
接口概要
鉴权要求
公开（无需令牌）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
Item
所属模块
天气预报
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| cityId | integer | 可选 | 城市 ID，如 440300 |
| city | string | 可选 | 城市名称，支持「北京」「深圳市」「beijing」等写法 |
请求示例7 种语言
该接口无需令牌，可直接调用。把示例中的参数值换成你的实际值即可。
curl -X GET 'https://boot.qingwu.ink/api/v1/weather/current?cityId=1' -H 'Accept: application/json'
const res = await fetch('https://boot.qingwu.ink/api/v1/weather/current?cityId=1', {
method: 'GET',
headers: {
'Accept': 'application/json',
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/weather/current?cityId=1",
headers={
"Accept": "application/json",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/weather/current?cityId=1"))
.header("Accept", "application/json")
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/weather/current?cityId=1", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/weather/current?cityId=1");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/weather/current?cityId=1 HTTP/1.1 Host: boot.qingwu.ink Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": {
"date": "2026-10-16",
"week": "星期五",
"weatherDay": "雷阵雨",
"weatherNight": "晴",
"tempHigh": 22,
"tempLow": 11,
"tempCurrent": 21,
"humidity": 85,
"windDirection": "东北风",
"windScale": "5级",
"aqi": 60,
"airQuality": "良",
"precipitation": 5.24,
"sunrise": "06:28",
"sunset": "18:02",
"tip": "有雷阵雨，注意防雷，尽量减少户外活动"
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 Item
| 字段 | 类型 | 说明 |
|---|---|---|
| date | string | 日期 例如 2026-10-16 |
| week | string | 星期 例如 星期五 |
| weatherDay | string | 白天天气 例如 晴 |
| weatherNight | string | 夜间天气 例如 多云 |
| tempHigh | integer | 最高气温 ℃ 例如 24 |
| tempLow | integer | 最低气温 ℃ 例如 14 |
| tempCurrent | integer | 当前气温 ℃（仅当天有效） 例如 21 |
| humidity | integer | 相对湿度 % 例如 48 |
| windDirection | string | 风向 例如 西北风 |
| windScale | string | 风力等级 例如 3级 |
| aqi | integer | 空气质量指数 例如 62 |
| airQuality | string | 空气质量等级 例如 良 |
| precipitation | number | 降水量 mm 例如 0.0 |
| sunrise | string | 日出时间 例如 06:12 |
| sunset | string | 日落时间 例如 17:48 |
| tip | string | 生活提示 |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 4001 | 暂无该城市的天气数据 |
| 4002 | 请指定城市名称或城市 ID |
说明
该接口为公开接口，无需任何凭证即可调用。
天气预报
未来预报
返回不含今天的未来若干天预报，days 默认 7、上限 15。
接口概要
鉴权要求
公开（无需令牌）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
array<Item>
所属模块
天气预报
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| cityId | integer | 可选 | 城市 ID，如 440300 |
| city | string | 可选 | 城市名称，支持「北京」「深圳市」「beijing」等写法 |
| days | integer | 可选 | 预报天数，1–15，默认 7 例如 7 |
请求示例7 种语言
该接口无需令牌，可直接调用。把示例中的参数值换成你的实际值即可。
curl -X GET 'https://boot.qingwu.ink/api/v1/weather/forecast?cityId=1&days=7' -H 'Accept: application/json'
const res = await fetch('https://boot.qingwu.ink/api/v1/weather/forecast?cityId=1&days=7', {
method: 'GET',
headers: {
'Accept': 'application/json',
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/weather/forecast?cityId=1&days=7",
headers={
"Accept": "application/json",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/weather/forecast?cityId=1&days=7"))
.header("Accept", "application/json")
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/weather/forecast?cityId=1&days=7", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/weather/forecast?cityId=1&days=7");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/weather/forecast?cityId=1&days=7 HTTP/1.1 Host: boot.qingwu.ink Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": [
{
"date": "2026-10-17",
"week": "星期六",
"weatherDay": "阴",
"weatherNight": "阴",
"tempHigh": 21,
"tempLow": 10,
"tempCurrent": null,
"humidity": 45,
"windDirection": "东风",
"windScale": "2级",
"aqi": 125,
"airQuality": "轻度污染",
"precipitation": 0.0,
"sunrise": "06:29",
"sunset": "18:01",
"tip": "天气舒适，适宜户外活动"
}
],
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 array<Item>
| 字段 | 类型 | 说明 |
|---|---|---|
| date | string | 日期 例如 2026-10-16 |
| week | string | 星期 例如 星期五 |
| weatherDay | string | 白天天气 例如 晴 |
| weatherNight | string | 夜间天气 例如 多云 |
| tempHigh | integer | 最高气温 ℃ 例如 24 |
| tempLow | integer | 最低气温 ℃ 例如 14 |
| tempCurrent | integer | 当前气温 ℃（仅当天有效） 例如 21 |
| humidity | integer | 相对湿度 % 例如 48 |
| windDirection | string | 风向 例如 西北风 |
| windScale | string | 风力等级 例如 3级 |
| aqi | integer | 空气质量指数 例如 62 |
| airQuality | string | 空气质量等级 例如 良 |
| precipitation | number | 降水量 mm 例如 0.0 |
| sunrise | string | 日出时间 例如 06:12 |
| sunset | string | 日落时间 例如 17:48 |
| tip | string | 生活提示 |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 4001 | 暂无该城市的天气数据 |
| 4002 | 请指定城市名称或城市 ID |
说明
该接口为公开接口，无需任何凭证即可调用。
天气预报
批量查询实况
一次查询多个城市的今日实况，适合城市对比或天气地图。
接口概要
鉴权要求
公开（无需令牌）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
array<Item>
所属模块
天气预报
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| cityIds | array<integer> | 必填 | 城市 ID 列表，逗号分隔，如 110000,440300 |
请求示例7 种语言
该接口无需令牌，可直接调用。把示例中的参数值换成你的实际值即可。
curl -X GET 'https://boot.qingwu.ink/api/v1/weather/batch' -H 'Accept: application/json'
const res = await fetch('https://boot.qingwu.ink/api/v1/weather/batch', {
method: 'GET',
headers: {
'Accept': 'application/json',
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/weather/batch",
headers={
"Accept": "application/json",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/weather/batch"))
.header("Accept", "application/json")
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/weather/batch", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/weather/batch");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/weather/batch HTTP/1.1 Host: boot.qingwu.ink Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": [
{
"date": "2026-10-16",
"week": "星期五",
"weatherDay": "晴",
"tempHigh": 22,
"tempLow": 11,
"tempCurrent": 13,
"humidity": 41,
"windDirection": "北风",
"windScale": "5级",
"aqi": 56,
"airQuality": "良",
"precipitation": 0.0,
"sunrise": "06:28",
"sunset": "18:02"
}
],
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 array<Item>
| 字段 | 类型 | 说明 |
|---|---|---|
| date | string | 日期 例如 2026-10-16 |
| week | string | 星期 例如 星期五 |
| weatherDay | string | 白天天气 例如 晴 |
| weatherNight | string | 夜间天气 例如 多云 |
| tempHigh | integer | 最高气温 ℃ 例如 24 |
| tempLow | integer | 最低气温 ℃ 例如 14 |
| tempCurrent | integer | 当前气温 ℃（仅当天有效） 例如 21 |
| humidity | integer | 相对湿度 % 例如 48 |
| windDirection | string | 风向 例如 西北风 |
| windScale | string | 风力等级 例如 3级 |
| aqi | integer | 空气质量指数 例如 62 |
| airQuality | string | 空气质量等级 例如 良 |
| precipitation | number | 降水量 mm 例如 0.0 |
| sunrise | string | 日出时间 例如 06:12 |
| sunset | string | 日落时间 例如 17:48 |
| tip | string | 生活提示 |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 4001 | 暂无该城市的天气数据 |
| 4002 | 请指定城市名称或城市 ID |
说明
单个城市失败不会中断整批请求，仅跳过并在服务端记录日志。
天气预报
搜索城市
复用地区搜索能力，返回可用于查询天气的城市列表，适合做城市输入联想。
接口概要
鉴权要求
公开（无需令牌）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
array<Region>
所属模块
天气预报
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| keyword | string | 必填 | 关键词，模糊匹配 |
| limit | integer | 可选 | 返回条数上限 例如 20 |
请求示例7 种语言
该接口无需令牌，可直接调用。把示例中的参数值换成你的实际值即可。
curl -X GET 'https://boot.qingwu.ink/api/v1/weather/cities?limit=20' -H 'Accept: application/json'
const res = await fetch('https://boot.qingwu.ink/api/v1/weather/cities?limit=20', {
method: 'GET',
headers: {
'Accept': 'application/json',
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/weather/cities?limit=20",
headers={
"Accept": "application/json",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/weather/cities?limit=20"))
.header("Accept", "application/json")
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/weather/cities?limit=20", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/weather/cities?limit=20");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/weather/cities?limit=20 HTTP/1.1 Host: boot.qingwu.ink Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": [
{
"id": 440300,
"parentId": 440000,
"name": "深圳市",
"shortName": null,
"level": 2,
"code": "440300",
"areaCode": null,
"pinyin": "shenzhenshi",
"sort": 3,
"status": 1
}
],
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 array<Region>
| 字段 | 类型 | 说明 |
|---|---|---|
| id | integer | 地区 ID（行政区划代码） 例如 110000 |
| parentId | integer | 上级地区 ID，顶级为 0 例如 0 |
| name | string | 地区名称 例如 北京市 |
| shortName | string | 简称 例如 京 |
| level | integer | 层级：1-省 2-市 3-区县 例如 1 |
| code | string | 行政区划代码字符串 例如 110000 |
| zipCode | string | 邮政编码 |
| areaCode | string | 电话区号 例如 010 |
| lng | number | 经度 |
| lat | number | 纬度 |
| pinyin | string | 拼音（支持拼音搜索） 例如 beijingshi |
| sort | integer | 排序值 |
| status | integer | 状态：1-启用 0-停用 |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 4001 | 暂无该城市的天气数据 |
| 4002 | 请指定城市名称或城市 ID |
说明
该接口为公开接口，无需任何凭证即可调用。
图片上传
上传图片
上传后按「业务类型 / 年 / 月 / 日」归档，返回可直接访问的 URL。
接口概要
鉴权要求
需登录（缺少有效令牌返回 401）
请求内容类型
multipart/form-data
响应内容类型
application/json
幂等性
非幂等，重复提交会产生多条数据
响应数据模型
UploadVO
所属模块
图片上传
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| type | string | 可选 | 业务目录，用于归档，如 avatar、news 例如 common |
请求体字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| file | string | 必填 | 文件 |
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X POST https://boot.qingwu.ink/api/v1/files/upload \ -H "Authorization: Bearer <accessToken>" \ -F "file=@avatar.png" \ -F "type=avatar"
const form = new FormData();
form.append('file', fileInput.files[0]);
const res = await fetch('https://boot.qingwu.ink/api/v1/files/upload?type=common', {
method: 'POST',
headers: {
'Authorization': `Bearer ${accessToken}`,
// 不要手动设置 Content-Type，浏览器会自动补上 boundary
},
body: form,
});
const { code, data } = await res.json();
console.log(code, data.url);import requests
resp = requests.post(
"https://boot.qingwu.ink/api/v1/files/upload?type=common",
headers={
"Authorization": f"Bearer {access_token}",
},
files={"file": open("avatar.png", "rb")},
)
print(resp.json()["data"]["url"])var boundary = "----QWApi" + System.currentTimeMillis();
var buf = new ByteArrayOutputStream();
buf.write(("--" + boundary + "\r\n"
+ "Content-Disposition: form-data; name=\"file\"; filename=\"avatar.png\"\r\n"
+ "Content-Type: application/octet-stream\r\n\r\n")
.getBytes(StandardCharsets.UTF_8));
Files.copy(Path.of("avatar.png"), buf);
buf.write(("\r\n--" + boundary + "--\r\n").getBytes(StandardCharsets.UTF_8));
var request = HttpRequest.newBuilder(URI.create("https://boot.qingwu.ink/api/v1/files/upload?type=common"))
.header("Authorization", "Bearer " + accessToken)
.header("Content-Type", "multipart/form-data; boundary=" + boundary)
.POST(HttpRequest.BodyPublishers.ofByteArray(buf.toByteArray()))
.build();
var res = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());var buf bytes.Buffer
w := multipart.NewWriter(&buf)
f, _ := os.Open("avatar.png")
defer f.Close()
fw, _ := w.CreateFormFile("file", "avatar.png")
io.Copy(fw, f)
w.Close()
req, _ := http.NewRequest("POST", "https://boot.qingwu.ink/api/v1/files/upload?type=common", &buf)
req.Header.Set("Authorization", "Bearer "+accessToken)
req.Header.Set("Content-Type", w.FormDataContentType())
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/files/upload?type=common");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => [
"file" => new CURLFile("avatar.png"),
],
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . $accessToken,
],
]);
echo curl_exec($ch);
curl_close($ch);POST /api/v1/files/upload?type=common HTTP/1.1 Host: boot.qingwu.ink Authorization: Bearer <accessToken> Content-Type: multipart/form-data; boundary=----QWApi ------QWApi Content-Disposition: form-data; name="file"; filename="avatar.png" Content-Type: application/octet-stream <file-bytes> ------QWApi--
响应示例
200 OK
{
"code": 200,
"message": "上传成功",
"data": {
"url": "/uploads/avatar/2026/10/16/9f3c1a2b7e4d.png",
"originalName": "avatar.png",
"size": 20480,
"contentType": "image/png"
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 UploadVO
| 字段 | 类型 | 说明 |
|---|---|---|
| url | string | 文件访问 URL 例如 /uploads/2026/10/16/a1b2c3.png |
| originalName | string | 原始文件名 例如 avatar.png |
| size | integer | 文件大小（字节） 例如 20480 |
| contentType | string | 文件类型 例如 image/png |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 201 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 413 | 上传文件超过 `spring.servlet.multipart.max-file-size` |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 5001 | 上传文件不能为空 |
| 5002 | 不支持的文件类型 |
| 5003 | 文件上传失败 |
说明
使用
multipart/form-data 提交。type 用于区分业务目录，如 avatar、news。支持 jpg/jpeg/png/gif/bmp/webp，单文件上限 10 MB；类型不符返回
5002。图片上传
删除文件
删除此前上传的文件。只接受本站 urlPrefix 下的地址，并做路径穿越校验。
接口概要
鉴权要求
需登录（缺少有效令牌返回 401）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
基本类型 / 空值
所属模块
图片上传
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| url | string | 必填 | 文件访问 URL，必须是本站上传返回的地址 |
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X DELETE 'https://boot.qingwu.ink/api/v1/files' -H 'Accept: application/json' -H 'Authorization: Bearer <accessToken>'
const res = await fetch('https://boot.qingwu.ink/api/v1/files', {
method: 'DELETE',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`,
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.delete(
"https://boot.qingwu.ink/api/v1/files",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {access_token}",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/files"))
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.DELETE()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("DELETE", "https://boot.qingwu.ink/api/v1/files", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer " + accessToken)
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/files");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "DELETE",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Authorization: Bearer " . $accessToken,
],
]);
echo curl_exec($ch);
curl_close($ch);DELETE /api/v1/files HTTP/1.1 Host: boot.qingwu.ink Authorization: Bearer <accessToken> Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "文件已删除",
"data": null,
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明
该接口的 data 为基本类型或空值，没有可展开的字段。
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
模块业务码
| 5001 | 上传文件不能为空 |
| 5002 | 不支持的文件类型 |
| 5003 | 文件上传失败 |
说明
需在请求头携带
Authorization: Bearer ；令牌过期请先用刷新令牌接口换取新的访问令牌。系统信息
健康检查
返回服务名、状态、服务器时间与 Java 版本，可供负载均衡探活。
接口概要
鉴权要求
公开（无需令牌）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
基本类型 / 空值
所属模块
系统信息
请求示例7 种语言
该接口无需令牌，可直接调用。把示例中的参数值换成你的实际值即可。
curl -X GET 'https://boot.qingwu.ink/api/v1/common/health' -H 'Accept: application/json'
const res = await fetch('https://boot.qingwu.ink/api/v1/common/health', {
method: 'GET',
headers: {
'Accept': 'application/json',
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/common/health",
headers={
"Accept": "application/json",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/common/health"))
.header("Accept", "application/json")
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/common/health", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/common/health");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/common/health HTTP/1.1 Host: boot.qingwu.ink Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": {
"application": "zm-api",
"status": "UP",
"time": "2026-10-16T09:25:26.071809300",
"javaVersion": "21.0.9"
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明由示例推导
| 字段 | 类型 | 说明 |
|---|---|---|
| application | string | — |
| status | string | — |
| time | string | — |
| javaVersion | string | — |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
说明
该接口为公开接口，无需任何凭证即可调用。
系统信息
服务器时间
返回服务器本地时间、毫秒时间戳与时区，用于前端校准或排查时区问题。
接口概要
鉴权要求
公开（无需令牌）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
基本类型 / 空值
所属模块
系统信息
请求示例7 种语言
该接口无需令牌，可直接调用。把示例中的参数值换成你的实际值即可。
curl -X GET 'https://boot.qingwu.ink/api/v1/common/time' -H 'Accept: application/json'
const res = await fetch('https://boot.qingwu.ink/api/v1/common/time', {
method: 'GET',
headers: {
'Accept': 'application/json',
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/common/time",
headers={
"Accept": "application/json",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/common/time"))
.header("Accept", "application/json")
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/common/time", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/common/time");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/common/time HTTP/1.1 Host: boot.qingwu.ink Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": {
"localDateTime": "2026-10-16T09:25:26.071809300",
"timestamp": 1792113926072,
"zone": "Asia/Shanghai"
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明由示例推导
| 字段 | 类型 | 说明 |
|---|---|---|
| localDateTime | string | — |
| timestamp | integer | — |
| zone | string | — |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
说明
该接口为公开接口，无需任何凭证即可调用。
系统信息
枚举字典
集中下发性别、用户状态、新闻状态、地区层级与排序方式等枚举，前端无需硬编码。
接口概要
鉴权要求
公开（无需令牌）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
基本类型 / 空值
所属模块
系统信息
请求示例7 种语言
该接口无需令牌，可直接调用。把示例中的参数值换成你的实际值即可。
curl -X GET 'https://boot.qingwu.ink/api/v1/common/enums' -H 'Accept: application/json'
const res = await fetch('https://boot.qingwu.ink/api/v1/common/enums', {
method: 'GET',
headers: {
'Accept': 'application/json',
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/common/enums",
headers={
"Accept": "application/json",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/common/enums"))
.header("Accept", "application/json")
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/common/enums", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/common/enums");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/common/enums HTTP/1.1 Host: boot.qingwu.ink Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": {
"gender": [
{
"value": 0,
"label": "未知"
},
{
"value": 1,
"label": "男"
},
{
"value": 2,
"label": "女"
}
],
"newsStatus": [
{
"value": 0,
"label": "草稿"
},
{
"value": 1,
"label": "已发布"
},
{
"value": 2,
"label": "已下架"
}
],
"newsOrderBy": [
{
"value": "latest",
"label": "最新发布"
},
{
"value": "hot",
"label": "浏览量最高"
}
]
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明由示例推导
| 字段 | 类型 | 说明 |
|---|---|---|
| gender | array | — |
| gender.value | integer | — |
| gender.label | string | — |
| newsStatus | array | — |
| newsStatus.value | integer | — |
| newsStatus.label | string | — |
| newsOrderBy | array | — |
| newsOrderBy.value | string | — |
| newsOrderBy.label | string | — |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
说明
该接口为公开接口，无需任何凭证即可调用。
操作日志
操作日志列表
分页查询审计记录，可按操作人、模块、操作描述关键词与执行结果过滤。
接口概要
鉴权要求
仅管理员（缺少有效令牌返回 401）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
PageResult<OperationLog>
所属模块
操作日志
查询与路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| pageNum | integer | 可选 | 页码，从 1 开始 |
| pageSize | integer | 可选 | 每页条数，最大 100 |
| keyword | string | 可选 | 关键词，模糊匹配 |
| success | integer | 可选 | 执行结果：1 成功 / 0 失败 |
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X GET 'https://boot.qingwu.ink/api/v1/logs?pageNum=1&pageSize=1&success=1' -H 'Accept: application/json' -H 'Authorization: Bearer <accessToken>'
const res = await fetch('https://boot.qingwu.ink/api/v1/logs?pageNum=1&pageSize=1&success=1', {
method: 'GET',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`,
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.get(
"https://boot.qingwu.ink/api/v1/logs?pageNum=1&pageSize=1&success=1",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {access_token}",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/logs?pageNum=1&pageSize=1&success=1"))
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.GET()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("GET", "https://boot.qingwu.ink/api/v1/logs?pageNum=1&pageSize=1&success=1", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer " + accessToken)
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/logs?pageNum=1&pageSize=1&success=1");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Authorization: Bearer " . $accessToken,
],
]);
echo curl_exec($ch);
curl_close($ch);GET /api/v1/logs?pageNum=1&pageSize=1&success=1 HTTP/1.1 Host: boot.qingwu.ink Authorization: Bearer <accessToken> Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作成功",
"data": {
"pageNum": 1,
"pageSize": 5,
"total": 1,
"pages": 1,
"list": [
{
"id": 12,
"userId": 1,
"username": "admin",
"module": "资讯管理",
"operation": "新增新闻",
"method": "POST /api/v1/news",
"ip": "127.0.0.1",
"costMs": 43,
"success": 1,
"errorMsg": null,
"createTime": "2026-10-16 09:31:07"
}
]
},
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明匹配模型 PageResult<OperationLog>
| 字段 | 类型 | 说明 |
|---|---|---|
| pageNum | integer | 当前页码 |
| pageSize | integer | 每页条数 |
| total | integer | 记录总数 |
| pages | integer | 总页数 |
| list | array<OperationLog> | 当前页的数据集合 |
| list.id | integer | 主键 ID |
| list.userId | integer | 操作人 ID |
| list.username | string | 操作人账号 |
| list.module | string | 模块 |
| list.operation | string | 操作描述 |
| list.method | string | 请求方法 + 路径 |
| list.params | string | 请求参数 |
| list.ip | string | 客户端 IP |
| list.costMs | integer | 耗时（毫秒） |
| list.success | integer | 是否成功：1-是 0-否 |
| list.errorMsg | string | 错误信息 |
| list.createTime | string | 创建时间 |
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 400 | 参数校验未通过，`message` 为具体字段的提示 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 403 | 已登录但不是管理员；或账号被禁用 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
说明
本组接口需要管理员角色，普通用户访问会返回 403。
日志由 AOP 切面自动写入，标注了
@LogOperation 的接口才会有记录。操作日志
清空操作日志
一次性清空全部审计记录，请谨慎使用。
接口概要
鉴权要求
仅管理员（缺少有效令牌返回 401）
请求内容类型
—
响应内容类型
application/json
幂等性
幂等，重复调用结果一致
响应数据模型
基本类型 / 空值
所属模块
操作日志
请求示例7 种语言
示例中的 <accessToken> 是占位符，请替换为登录接口返回的令牌。
curl -X DELETE 'https://boot.qingwu.ink/api/v1/logs' -H 'Accept: application/json' -H 'Authorization: Bearer <accessToken>'
const res = await fetch('https://boot.qingwu.ink/api/v1/logs', {
method: 'DELETE',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`,
},
});
const { code, message, data } = await res.json();
console.log(code, data);import requests
resp = requests.delete(
"https://boot.qingwu.ink/api/v1/logs",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {access_token}",
},
)
print(resp.json()["data"])var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://boot.qingwu.ink/api/v1/logs"))
.header("Accept", "application/json")
.header("Authorization", "Bearer " + accessToken)
.DELETE()
.build();
var res = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());req, err := http.NewRequest("DELETE", "https://boot.qingwu.ink/api/v1/logs", nil)
if err != nil { log.Fatal(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer " + accessToken)
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()$ch = curl_init("https://boot.qingwu.ink/api/v1/logs");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "DELETE",
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Authorization: Bearer " . $accessToken,
],
]);
echo curl_exec($ch);
curl_close($ch);DELETE /api/v1/logs HTTP/1.1 Host: boot.qingwu.ink Authorization: Bearer <accessToken> Accept: application/json
响应示例
200 OK
{
"code": 200,
"message": "操作日志已清空",
"data": null,
"timestamp": 1792113842032,
"success": true
}完整响应对照 基础约定 中的统一响应结构。
响应字段说明
该接口的 data 为基本类型或空值，没有可展开的字段。
状态码与错误码
| 状态码 | 出现场景 |
|---|---|
| 200 | 请求成功，业务码与 HTTP 状态码保持一致 |
| 401 | 未携带令牌、令牌无效或已过期 |
| 403 | 已登录但不是管理员；或账号被禁用 |
| 500 | 服务端未捕获的异常，`message` 为简要原因；详细堆栈见服务端日志 |
说明
本组接口需要管理员角色，普通用户访问会返回 403。
该接口要求管理员角色：普通用户即使携带有效令牌也会被拒绝（HTTP 403，业务码
1011）。