API 接口总览

以当前控制器路由与宿主配置为准，本文不再维护大段未验证的接口示例，重点说明真实入口、路由前缀与返回模型。

统一入口

默认主宿主

FreeKit.Host 的默认路径前缀来自 ASPNETCORE_PATHBASE=/kit_api。

本地开发常用入口：

工具	地址
Swagger UI	https://localhost:7002/kit_api/swagger
RapiDoc	https://localhost:7002/kit_api/r
健康检查	https://localhost:7002/kit_api/health

容器部署常用入口：

工具	地址
Swagger UI	http://localhost:18080/kit_api/swagger
RapiDoc	http://localhost:18080/kit_api/r
健康检查	http://localhost:18080/kit_api/health

其他默认宿主

宿主	Swagger 地址
FreeKit.Job.Host	https://localhost:7000/job_api/swagger
FreeKit.MessageHandler.Host	https://localhost:7003/message_api/swagger

Swagger 分组

主宿主当前注册的 Swagger 分组来自 FreeKit.Host\Program.cs：

• v1
• identity
• plat
• cms
• cms-admin
• im

如果你要找某个接口，优先去 Swagger/RapiDoc 查看对应分组，而不是依赖旧文档示例。

统一响应模型

仓库使用 IGeekFan.FreeKit.Infrastructure.DTO\ApiResponse：

{
  "code": 0,
  "message": "操作成功"
}

带数据的形式为：

{
  "code": 0,
  "message": "操作成功",
  "data": {}
}

对应代码结构：

• ApiResponse：Code、Message
• ApiResponse<T>：Code、Message、Data

常见响应码

下表来自 ResponseCode 枚举：

Code	枚举	说明
0	Success	成功
1001	BusinessException	业务异常
1002	Failed	操作失败
999	ServerUnknownError	服务器未知错误
10000	AuthenticationFailed	未登录 / 认证失败
10001	NoPermission	无权限
10020	NotFound	资源不存在
10030	ParameterError	参数错误
10040	TokenInvalidation	Token 无效
10050	TokenExpired	Token 过期
10140	ManyRequests	请求过于频繁
40001	BadFileToken	文件令牌错误

真实路由前缀

以下前缀来自当前控制器路由定义：

模块	典型前缀	示例控制器
Identity	api/identity/*	AccountController、ProfileController、RoleController
CmsKit	api/cms/*	ArticleController、CommentController、SearchController
CmsKit 管理端	api/cms/admin/*	Admin.ArticleController、Admin.CommentController
Platform	api/plat/*	AreaController、CatalogController、TaskBuildController
Short	api/plat/short_urls	ShortUrlController
IM	api/im/*	ChatMessageController、ChatGroupController
ToDo	api/v1/ToDo	ToDoController
Holiday	api/v1/Holiday	HolidayController
ToolKit	api/v1/*	ProxyController、CnBlogController、SMController
DailyHot	api/dailyhot	DailyHotController
Tenant	api/tenants	TenantController

已验证的代表性资源

Identity

• api/identity/account
• api/identity/profile
• api/identity/oauth2
• api/identity/role
• api/identity/permission

CmsKit

• api/cms/articles
• api/cms/articles/draft
• api/cms/comments
• api/cms/short_msg
• api/cms/search
• api/cms/recommendations
• api/cms/notifications

Platform / Short

• api/plat/area
• api/plat/catalog
• api/plat/navitem
• api/plat/task-build
• api/plat/short_urls
• api/dailyhot

IM

• api/im/chat-messages
• api/im/chat-groups
• api/im/friends
• api/im/users
• api/im/user-presence

实时与非 HTTP 入口

主宿主额外暴露：

类型	地址	说明
SignalR Hub	/kit_api/hubs/onlineuser	在线用户 Hub
SignalR Hub	/kit_api/hubs/notifications	CmsKit 通知 Hub
gRPC	/kit_api 宿主内 AccessKeyService	主宿主映射的 gRPC 服务

如何查某个接口

1. 先看主宿主 Swagger 分组。
2. 再按路由前缀去对应模块目录找控制器。
3. 如果是 Job / Message 相关接口，到对应宿主 Swagger 查看。