API 接口文档

FreeKitModules 统一 API 规范与核心接口速查表

📋 目录

• API 基础规范
• 认证授权
• BasicIdentity 模块
• CmsKit 模块
• ToDo 模块
• Platform 模块
• 错误码对照表

---

API 基础规范

统一响应格式

所有 API 返回统一的 JSON 格式：

成功响应：

{
  "success": true,
  "data": { ... },
  "message": null,
  "errors": null
}

失败响应：

{
  "success": false,
  "data": null,
  "message": "错误描述",
  "errors": [
    {
      "field": "Email",
      "message": "邮箱格式不正确"
    }
  ]
}

分页响应：

{
  "success": true,
  "data": {
    "items": [ ... ],
    "totalCount": 100,
    "pageIndex": 1,
    "pageSize": 20,
    "totalPages": 5
  }
}

统一分页参数

GET /api/Article?pageIndex=1&pageSize=20&sortBy=CreateTime&sortOrder=desc

参数	类型	默认值	说明
pageIndex	int	1	页码（从 1 开始）
pageSize	int	20	每页数量（最大 100）
sortBy	string	CreateTime	排序字段
sortOrder	string	desc	排序方向（asc/desc）

请求头规范

Content-Type: application/json
Authorization: Bearer {access_token}
X-Request-Id: {unique-request-id}
Accept-Language: zh-CN

时间格式

统一使用 ISO 8601 格式：

{
  "createTime": "2025-11-24T10:30:00+08:00"
}

---

认证授权

JWT Token 结构

Access Token (有效期 2 小时)：

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.payload.signature

Refresh Token (有效期 7 天)：

3fa85f64-5717-4562-b3fc-2c963f66afa6

使用 Token

GET /api/Article
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token 刷新

当 access_token 过期时（401 错误），使用 refresh_token 获取新 token：

POST /api/Account/RefreshToken
Content-Type: application/json

{
  "refreshToken": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

响应：

{
  "success": true,
  "data": {
    "access_token": "new_access_token",
    "refresh_token": "new_refresh_token",
    "expires_in": 7200
  }
}

---

BasicIdentity 模块

基础认证功能（账户管理、登录注册）

用户注册

POST /api/Account/Register
Content-Type: application/json

{
  "userName": "testuser",
  "nickName": "测试用户",
  "email": "test@example.com",
  "password": "Password123!",
  "phoneNumber": "13800138000"
}

响应：

{
  "success": true,
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "userName": "testuser",
    "nickName": "测试用户",
    "email": "test@example.com"
  }
}

用户登录

POST /api/Account/Login
Content-Type: application/json

{
  "userName": "testuser",
  "password": "Password123!"
}

响应：

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "expires_in": 7200,
    "user": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "userName": "testuser",
      "nickName": "测试用户",
      "avatarKey": "avatars/user123.jpg"
    }
  }
}

获取当前用户信息

GET /api/Profile/UserInfo
Authorization: Bearer {access_token}

退出登录

POST /api/Account/Logout
Authorization: Bearer {access_token}

---

CmsKit 模块

内容管理系统（文章、沸点、评论）

文章管理

发布文章

POST /api/Article
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "title": "文章标题",
  "content": "# Markdown 内容\n\n文章正文...",
  "excerpt": "文章摘要",
  "keywords": "标签1,标签2",
  "thumbnail": "https://example.com/cover.jpg",
  "editor": 1,
  "articleSource": 1,
  "tagIds": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ]
}

字段说明：

• editor: 1=Markdown, 2=富文本
• articleSource: 1=原创, 2=转载, 3=翻译

获取文章列表

GET /api/Article?pageIndex=1&pageSize=20&auditStatus=2&recommend=true

查询参数：

• auditStatus: 审核状态（1=待审核, 2=已通过, 3=未通过）
• recommend: 是否推荐（true/false）
• createUserId: 作者 ID
• keyword: 搜索关键词

获取文章详情

GET /api/Article/{id}

更新文章

PUT /api/Article/{id}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "title": "更新后的标题",
  "content": "更新后的内容"
}

删除文章

DELETE /api/Article/{id}
Authorization: Bearer {access_token}

点赞文章

POST /api/Article/{id}/Like
Authorization: Bearer {access_token}

收藏文章

POST /api/Article/{id}/Collect
Authorization: Bearer {access_token}

评论管理

发表评论

POST /api/Comment
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "subjectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "subjectType": 1,
  "text": "评论内容",
  "parentId": null,
  "respUserId": null
}

字段说明：

• subjectType: 1=文章评论, 2=沸点评论, 3=标签评论
• parentId: 父评论 ID（回复评论时填写）
• respUserId: 被回复用户 ID

获取评论列表

GET /api/Comment?subjectId={articleId}&subjectType=1&pageIndex=1&pageSize=20

删除评论

DELETE /api/Comment/{id}
Authorization: Bearer {access_token}

沸点管理

发布沸点

POST /api/ShortMsg
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "content": "沸点内容",
  "topicId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "pictures": [
    "https://example.com/pic1.jpg",
    "https://example.com/pic2.jpg"
  ]
}

获取沸点列表

GET /api/ShortMsg?topicId={topicId}&pageIndex=1&pageSize=20

---

ToDo 模块

待办事项管理

创建待办

POST /api/ToDo
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "message": "待办事项内容",
  "notificationTime": "2025-12-01T09:00:00"
}

获取待办列表

GET /api/ToDo?isDone=false&pageIndex=1&pageSize=20

查询参数：

• isDone: 是否完成（true/false）
• message: 搜索关键词

更新待办

PUT /api/ToDo/{id}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "message": "更新后的内容",
  "isDone": true
}

批量标记完成

POST /api/ToDo/MakeDones
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "ids": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "4fa85f64-5717-4562-b3fc-2c963f66afa7"
  ],
  "isDone": true
}

删除待办

DELETE /api/ToDo/{id}
Authorization: Bearer {access_token}

---

Platform 模块

平台服务（行政区域、短链接、热点数据）

行政区域

获取省份列表

GET /api/Area?deep=1

deep 参数：

• 1=省级
• 2=市级
• 3=区县级

获取城市列表

GET /api/Area?parentId={provinceId}&deep=2

短链接

生成短链接

POST /api/ShortUrl
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "originalUrl": "https://example.com/very/long/url/path?param=value",
  "customCode": "mylink",
  "expireTime": "2025-12-31T23:59:59"
}

响应：

{
  "success": true,
  "data": {
    "shortUrl": "https://s.example.com/mylink",
    "code": "mylink",
    "expireTime": "2025-12-31T23:59:59"
  }
}

访问短链接

GET /s/{code}

自动重定向到原始 URL

每日热点

获取热点数据

GET /api/DailyHot?source=weibo&pageIndex=1&pageSize=20

source 参数：

• weibo: 微博热搜
• github: GitHub Trending
• juejin: 掘金热门
• bilibili: B站热门

---

错误码对照表

HTTP 状态码	错误码	说明	解决方案
200	0	成功	-
400	1001	参数验证失败	检查请求参数格式
401	2001	未认证	提供有效的 access_token
401	2002	Token 过期	使用 refresh_token 刷新
403	3001	权限不足	检查用户角色与权限
404	4001	资源不存在	检查资源 ID 是否正确
409	5001	资源冲突	用户名/邮箱已存在等
422	6001	业务逻辑错误	查看 message 详细说明
429	7001	请求过于频繁	降低请求频率
500	9001	服务器内部错误	查看日志或联系管理员

常见业务错误码

错误码	说明
1001	用户名或密码错误
1002	用户已被禁用
1003	邮箱未验证
2001	文章审核未通过
2002	评论已被删除
3001	待办事项不存在
4001	短链接已过期

---

🔍 更多信息

• 完整 API 文档：访问 Swagger UI https://localhost:5001/swagger

• 模块详细说明：

  • CmsKit 功能清单
  • Identity 功能清单
  • Platform 功能清单
  • ToDo 功能清单

• 开发指南：参考各模块的 README 与实体参考文档

• 快速入门：GETTING_STARTED.md

---

最后更新: 2025年11月24日