教程：从零创建一个业务模块

本教程带你用 FreeKit 框架约定，从空项目搭建一个最小可用的「公告（Notice）」业务模块，串联 Core（审计实体/DI 标记）+ Extras（FreeSql 仓储）+ Modularity（模块化启动） 三大基础能力。

目标

• 定义一个带审计字段的实体 Notice
• 通过 Manager / Service 分层封装逻辑
• 以 IModuleStartup 挂载模块，路由自动带 /api/notice 前缀
• 提供增删查接口

1. 定义实体（Core）

继承 FullAuditEntity，自动获得创建/修改/删除审计字段与软删除：

using IGeekFan.FreeKit.Extras.AuditEntity;

public class Notice : FullAuditEntity<Guid, Guid>
{
    public string Title { get; set; } = default!;
    public string Content { get; set; } = default!;
    public bool IsPublished { get; set; }
}

2. 领域服务（Manager）

按约定接口 INoticeManager / NoticeManager，并标记 IScopedDependency 由 Autofac 自动注册：

public interface INoticeManager : IScopedDependency
{
    Task<Notice> CreateAsync(string title, string content);
}

public class NoticeManager : INoticeManager
{
    private readonly IBaseRepository<Notice, Guid> _repository;

    public NoticeManager(IBaseRepository<Notice, Guid> repository) => _repository = repository;

    public async Task<Notice> CreateAsync(string title, string content)
    {
        var notice = new Notice { Title = title, Content = content, IsPublished = true };
        return await _repository.InsertAsync(notice);
    }
}

3. 应用服务（Service）

public interface INoticeService : IScopedDependency
{
    Task<Guid> PublishAsync(string title, string content);
}

public class NoticeService : INoticeService
{
    private readonly INoticeManager _manager;

    public NoticeService(INoticeManager manager) => _manager = manager;

    public async Task<Guid> PublishAsync(string title, string content)
    {
        var notice = await _manager.CreateAsync(title, content);
        return notice.Id;
    }
}

4. 控制器

[Route("api/[module]/[controller]")] 中的 [module] 由模块名解析，本例路由即 /api/notice/notice：

[ApiController]
[Route("api/[module]/[controller]")]
public class NoticeController : ControllerBase
{
    private readonly INoticeService _service;

    public NoticeController(INoticeService service) => _service = service;

    [HttpPost]
    public async Task<IActionResult> Publish(PublishRequest request)
    {
        var id = await _service.PublishAsync(request.Title, request.Content);
        return Ok(id);
    }
}

public record PublishRequest(string Title, string Content);

5. 模块启动（Modularity）

实现 IModuleStartup，在 ConfigureServices 注册 FreeSql 仓储与本次新增的服务：

public class NoticeStartup : IModuleStartup
{
    public void ConfigureServices(IServiceCollection services, IConfiguration configuration)
    {
        // FreeSql 仓储（假设主宿主已注册 IFreeSql）
        services.AddFreeRepository(typeof(Notice).Assembly);
        services.AddScoped<INoticeManager, NoticeManager>();
        services.AddScoped<INoticeService, NoticeService>();
    }
}

在 src/Services/Host/FreeKit.DI/E.cs 注册模块：

{ "notice", typeof(NoticeStartup) }

6. 运行验证

dotnet run --project src/Services/Host/FreeKit.Host

访问 {pathBase}/swagger，找到 Notice 分组，调用 POST /api/notice/notice 即可发布公告。

小结

层	约定	本教程对应
Domain	IXxxManager / XxxManager	INoticeManager
Application	IXxxService / XxxService	INoticeService
Controllers	XxxController + [module] 路由	NoticeController
启动	IModuleStartup	NoticeStartup

更复杂的场景（DTO 校验、领域事件、事务、CrudAppService 基类）见 Core、Extras 与 模块化单体。批量生成样板代码可参考 CLI 脚手架 或 CodeGen 代码生成。