跳到主要内容

项目入门指南

以仓库根目录和默认宿主 src/Services/Host/FreeKit.Host 为主，从“能跑起来、知道怎么配、看懂结构、能改代码”四步入门。

1. 先认清项目边界​

FreeKitModules 不是单一业务系统，而是一套 .NET 10 的模块化 Monolith / 微服务项目，代码结构分成三层：

  • src/BuildingBlocks/：公共基础设施库，提供模块化、通用能力和基础组件
  • src/Services/：业务模块与宿主项目，包含 CmsKit、Identity、Platform、Holiday、ToDo、Member、Short、Auth、CodeGen 等
  • src/Test/：单元测试和集成测试

你在入门时不要只盯着某个模块，要先看整套项目如何“宿主 + 模块 + 基础设施”协作。

2. 先从哪些代码入口看起​

建议的阅读顺序：

  1. README.md 先看仓库级概览
  2. tech-stack.md 看技术选型和宿主结构
  3. configuration.md 看配置项和路径前缀
  4. API 总览 看真实路由和入口
  5. new-module-guide.md 看模块化开发方式

如果要直接看代码，优先看这些文件：

  • src/Services/Host/FreeKit.Host/Program.cs
  • src/Services/Host/FreeKit.Host/FreeKit.Host.csproj
  • src/Services/Host/FreeKit.DI/E.cs
  • src/Services/CmsKit/FreeKit.CmsKit/CmsKitModuleStartup.cs
  • src/Services/Identity/FreeKit.Identity/IdentityModuleStartup.cs
  • src/Services/Identity/FreeKit.Identity.Host/Program.cs
  • IM 模块请先从 src/Services/IM/FreeKit.IM.Host 的宿主结构和仓库内对应模块文档入手

3. 整个项目是怎么启动的​

默认开发路径不是先跑某个模块，而是先跑宿主：

  • 主 API 宿主：src/Services/Host/FreeKit.Host
  • 任务宿主：src/Services/Host/FreeKit.Job.Host
  • 消息宿主：src/Services/Host/FreeKit.MessageHandler.Host
  • 健康检查：src/Services/Host/FreeKit.HealthChecks

本地启动顺序​

  1. 安装 .NET SDK 10.0+
  2. 准备 MySQL、Redis，按需准备 RabbitMQ 和 MeiliSearch
  3. 配置 src/Services/Host/FreeKit.Host/appsettings.Development.json
  4. 启动主宿主
  5. 按需再启动 Job、Message、HealthChecks

常用命令​

dotnet restore FreeKitModules.sln
dotnet run --project src/Services/Host/FreeKit.Host --launch-profile https-dev
dotnet run --project src/Services/Host/FreeKit.Job.Host --launch-profile https-dev
dotnet run --project src/Services/Host/FreeKit.MessageHandler.Host --launch-profile https-dev

如果你是 Windows 用户，也可以直接使用仓库提供的脚本：

  • build/run_freekit_pro_modules.bat
  • build/run_freekit_pro_modules.bash

4. 你必须先知道哪些配置​

主宿主配置文件​

  • src/Services/Host/FreeKit.Host/appsettings.Development.json
  • src/Services/Host/FreeKit.Job.Host/appsettings.Development.json
  • src/Services/Host/FreeKit.MessageHandler.Host/appsettings.Development.json

关键配置段​

配置段作用典型影响
ConnectionStrings主数据库和 Redis影响 FreeSql、缓存、连接管理
MeiliSearch搜索引擎配置影响全文搜索、索引同步
Search搜索行为参数影响建议、热词、结果排序
FileStorage / FileStorageOption文件存储影响附件、图片、同步
HotIndex热度计算参数影响热榜和推荐
Host:IdentityApi跨模块用户接口影响用户资料、头像、昵称

路径前缀​

当前项目常见路径前缀不是固定的，取决于宿主的 ASPNETCORE_PATHBASE：

  • 主 API：/kit_api
  • Job：/job_api
  • Message：/message_api

这会直接影响 Swagger、RapiDoc、Hub 和业务 API 的最终地址。

5. 项目里有哪些核心技术​

FreeSql​

项目使用 FreeSql CodeFirst，同步表结构的入口在模块启动阶段完成。你在改实体时，要同步考虑：

  • 表结构是否会自动变化
  • 索引是否需要新增或调整
  • 软删除字段是否会影响查询结果

Redis / FreeRedis​

Redis 在项目里不只是缓存，还承担：

  • SignalR 连接映射
  • 实时消息广播
  • 部分模块的状态同步

SignalR​

实时通信主要用于通知和在线状态。你需要知道：

  • Hub 会映射到宿主路径
  • 多实例环境下依赖 Redis 做连接协调
  • 通知不能只看单机逻辑

MeiliSearch​

全文搜索和索引同步依赖 MeiliSearch。改内容类功能时，要同步考虑：

  • 新增内容后是否入索引
  • 更新后是否重建索引
  • 删除后是否清理索引
  • 私密内容是否应该进入公开搜索结果

CAP / RabbitMQ​

项目里有消息驱动能力，适合做跨模块事件、异步通知、后台解耦。

6. 模块是怎么组织的​

主模块入口由 src/Services/Host/FreeKit.DI/E.cs 管理，默认启用的模块通常包括：

  • Identity
  • Platform
  • Holiday
  • ToDo
  • CmsKit
  • Toolkit
  • Member
  • Short

读代码时怎么区分职责​

  • Host 负责装配和启动
  • ModuleStartup 负责模块注册和配置
  • Controllers 负责 HTTP 接口
  • Application 负责业务编排
  • Domain 负责业务规则
  • Models 负责实体映射

7. 新手应该怎么学这套项目​

推荐顺序​

  1. 先跑主宿主，确认接口和 Swagger 能访问
  2. 再看 FreeKit.DI/E.cs，搞清楚当前启用了哪些模块
  3. 然后选一个模块读完整链路，比如 CmsKit 或 Identity
  4. 最后看具体配置、仓储和实体

先学什么最值​

  • 想做业务开发：先看 CmsKit 和 Identity
  • 想做实时功能：先看 SignalR 和 Platform 通知模块
  • 想做系统配置：先看 Host、Job、Message 三个宿主
  • 想做公共能力：先看 BuildingBlocks

8. 开发时最常见的坑​

  • 只改某个模块，不看宿主是否注册
  • 改了配置，却没有同步到对应宿主的 appsettings
  • 只看 Controller，不看 Application 和 Domain
  • 改完实体后忘了检查 CodeFirst 同步结果
  • 改了内容却忘记搜索索引和通知链路

9. 最实用的调试顺序​

当功能“不工作”时，先按这个顺序排查：

  1. 配置是否加载正确
  2. 服务是否注册到容器
  3. 数据表是否同步
  4. 路由是否挂载到正确宿主
  5. 索引和缓存是否更新
  6. 权限、审核、隐私是否拦截了结果
  7. 前端路径是否和宿主前缀一致

10. 如果你要做二次开发​

最稳妥的做法是先从一个模块开始，不要同时改多个模块：

  • 先选 CmsKit 做业务样例
  • 再选 Identity 看权限和用户
  • 再选 Platform 看通知和实时通信
  • 最后再改 Host 和 BuildingBlocks

11. 相关文档​

12. 一句话总结​

FreeKitModules 的入门，不是先学某个业务模块，而是先学“宿主怎么启动、模块怎么注册、配置怎么传递、索引和实时能力怎么接起来”，然后再进入具体业务。