版本：3.0.0

快速开始

按这篇做完，你手里会有一个最小可用的 Aegis 项目：

能启动
能查数据库
能打开 Swagger
能写日志

默认环境是 .NET 8 + Aegis 3.x。
先别追求一步到位，第一版先跑通最重要。

准备工作

一个 ASP.NET Core Web API 项目，目标框架 net8.0
一个可访问的数据库
Aegis 3.x 相关包或项目引用
NLog.config

项目结构先按这个拆：

YourSolution
├── YourApp.WebApi
├── YourApp.Contract
├── YourApp.Services
├── YourApp.Dto
└── YourApp.Repository

1. 改入口

先把入口收干净，不要在这里塞别的启动逻辑。

using Aegis.Core.Infrastructure;

AegisApplication.Run(args);

2. 加 `Component.deps.json`

在起步阶段，确保将最基础也是最核心的四个组件（日志、Swagger、业务服务和请求验证）全部打开：

{
  "Components": {
    "Services": [
      "Logging",
      "Swagger",
      "BusinessServices",
      "RequestValidation"
    ],
    "Middlewares": [
      "Swagger"
    ]
  }
}

这主要完成四件事：

接日志 (Logging)
注册业务服务 (BusinessServices)
开 Swagger (Swagger)
启用请求验证 (RequestValidation)

3. 配 `appsettings.json`

先只放数据库、Swagger、日志三类配置：

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "Aegis": {
    "ApplicationName": "YourApp.WebApi",
    "Environment": "Development"
  },
  "PostgreConnection": "Host=127.0.0.1;Database=aegis_db;Port=5432;Username=postgres;Password=pass",
  "Swagger": {
    "IsEnabled": true,
    "Title": "YourApp API",
    "Version": "v1",
    "XmlCommentsPath": "{CurrentDirectory}/{CurrentProject}.xml",
    "ExtensionXmlComments": [
      "{CurrentDirectory}/*.Dto.xml"
    ]
  }
}

提示： appsettings.json 如果没有包含这些基础节点，框架或日志可能无法正常工作。

如果你用 SqlServer，把连接串和后面的 DataType 一起改掉。

4. 在宿主项目里放一个 `NLog.config`

为了让日志组件能真正把日志写到文件，你必须在 WebApi 根目录下提供 NLog.config（记得在项目属性里设为“如果较新则复制”）：

<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      autoReload="true"
      internalLogLevel="Info"
      internalLogFile="internal-nlog.txt">

  <targets async="true">
    <target name="file" xsi:type="File"
            fileName="${basedir}/Logs/${shortdate}.log"
            layout="${longdate} | ${level:uppercase=true} | ${logger} | ${message} ${exception:format=tostring}" />
    <target name="console" xsi:type="Console"
            layout="${longdate} | ${level:uppercase=true} | ${logger} | ${message} ${exception:format=tostring}" />
  </targets>

  <rules>
    <logger name="Microsoft.*" minlevel="Warning" writeTo="console,file" />
    <logger name="*" minlevel="Info" writeTo="console,file" />
  </rules>
</nlog>

5. 建数据库源

这里先别想复杂，先把数据库连接标识建出来。

using Aegis.Core.FreeSql;

namespace YourApp.Repository;

public class AppDb : IDbSource
{
    public AppDb(IFreeSql<AppDb> sqlClient)
    {
        SqlClient = sqlClient;
    }

    public IFreeSql<AppDb> SqlClient { get; }
}

5. 建实体和仓储

第一版先写到能查出一条数据就够了。

using FreeSql.DataAnnotations;

namespace YourApp.Repository.Entities;

[Table(Name = "User")]
public class UserEntity
{
    [Column(IsPrimary = true)]
    public long Id { get; set; }

    public string Name { get; set; }
}

using FreeSql;
using YourApp.Repository.Entities;

namespace YourApp.Repository.Repositories;

public class UserRepository : BaseRepository<UserEntity, long>
{
    public UserRepository(IFreeSql<AppDb> fsql) : base(fsql)
    {
    }

    public Task<UserEntity> GetByIdAsync(long id)
    {
        return this.Where(x => x.Id == id).FirstAsync();
    }
}

6. 在 `Startup` 里注册数据库和仓储

这一段写完，数据库主链路基本就通了。

using Aegis.Configuration;
using Aegis.Core.FreeSql;
using Aegis.Core.Infrastructure;
using YourApp.Repository;

namespace YourApp.WebApi;

public sealed class Startup : ICustomStartup
{
    public void ConfigureServices(IServiceCollection services)
    {
        var connectionString = ConfigManager.Get("PostgreConnection");

        services.AddDbSource<AppDb>(x =>
        {
            x.ConnectionString = connectionString;
            x.DataType = "PostgreSQL";
        });

        services.AddDbRepositories<AppDb>();
    }

    public void Configure(IApplicationBuilder app)
    {
    }
}

7. 建 Contract、Service、Request 和 Dto

做到这里，业务主链路就差最后一个 Controller 了。

Contract

using Aegis.Services;
using YourApp.Dto;
using YourApp.Dto.Requests;

namespace YourApp.Contract;

public interface IUserContract : IBusinessService
{
    Task<UserDto?> GetUserAsync(GetUserRequest request);
}

Request

namespace YourApp.Dto.Requests;

public record GetUserRequest
{
    public long Id { get; init; }
}

Dto

namespace YourApp.Dto;

public record UserDto
{
    public long Id { get; init; }
    public string Name { get; init; }
}

Service

using YourApp.Contract;
using YourApp.Dto;
using YourApp.Dto.Requests;
using YourApp.Repository.Repositories;

namespace YourApp.Services;

public class UserService : IUserContract
{
    private readonly UserRepository _userRepository;

    public UserService(UserRepository userRepository)
    {
        _userRepository = userRepository;
    }

    public async Task<UserDto?> GetUserAsync(GetUserRequest request)
    {
        var entity = await _userRepository.GetByIdAsync(request.Id);
        if (entity == null)
        {
            return null;
        }

        return new UserDto
        {
            Id = entity.Id,
            Name = entity.Name
        };
    }
}

这里记住一条就行：

Service 不直接碰 IFreeSql
数据访问统一走 Repository

8. 建一个最小 Controller

先做一个最小接口，让请求能走到数据库，再从标准响应返回出来。

using Aegis.Core.Infrastructure.Controller;
using Aegis.Transfer.Responses;
using Microsoft.AspNetCore.Mvc;
using YourApp.Contract;
using YourApp.Dto.Requests;

namespace YourApp.WebApi.Controllers;

public class UserController : ApiControllerBase
{
    private readonly IUserContract _userService;

    public UserController(IUserContract userService)
    {
        _userService = userService;
    }

    [HttpPost("GetUser")]
    public async Task<ApiResponse> GetUser(GetUserRequest request)
    {
        var dto = await _userService.GetUserAsync(request);
        if (dto == null)
        {
            return FailedResult("用户不存在");
        }

        return SuccessResult(dto);
    }
}

返回方式也统一一下：

对外都返回 ApiResponse
单对象用 SuccessResult
列表用 SuccessListResult

9. 放 `NLog.config`

在 WebApi 项目根目录放一个最小 NLog.config：

<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <targets async="true">
    <target name="file"
            xsi:type="File"
            fileName=".\Logs\${level}\_${shortdate}.log" />
  </targets>
  <rules>
    <logger name="*" minlevel="Info" writeTo="file" />
  </rules>
</nlog>

别忘了复制到输出目录。

10. 启动后检查这 4 件事

项目能正常启动
浏览器能打开 /swagger/index.html
调用 GetUser 能拿到标准响应
运行目录下能看到日志输出

这四件事都通过，第一版就算通了。

接下来再看

想先把分层关系理顺：看层次介绍
想看配置：看配置
想看日志：看日志
想看响应：看 ApiControllerBase
想验收：看初始系统验证清单

准备工作​

1. 改入口​

2. 加 Component.deps.json​

3. 配 appsettings.json​

4. 在宿主项目里放一个 NLog.config​

5. 建数据库源​

5. 建实体和仓储​

6. 在 Startup 里注册数据库和仓储​

7. 建 Contract、Service、Request 和 Dto​

8. 建一个最小 Controller​

9. 放 NLog.config​

10. 启动后检查这 4 件事​

接下来再看​