开发 API

Minimal APIs

Lino 默认采用 Minimal API 风格生成端点，优先考虑：

• 清晰度 – 代码简洁、直接且具有表达力。
• 性能 – 响应优化，无不必要的开销。

集成功能

TypedResults：确保强类型响应，有助于可读性和 OpenAPI 生成。

API 版本控制：端点可以演进而不破坏兼容性。

丰富的文档：可配置的元数据直接嵌入 OpenAPI，包括：

• WithTags → 在 OpenAPI 中将端点分组到逻辑部分。
• WithName → 一致地定义 operationId。
• WithSummary → 清楚描述端点的用途。
• Produces(statusCode, schema) → 指定状态码和响应契约。
• MapToApiVersion → 允许公开同一端点的不同版本。

请求与响应

Record classes 默认用于请求和响应：

• 是不可变的（减少副作用和 bug）。
• 简洁且易于阅读。

与 CQRS 集成：

• 通过端点接收的请求会被转换为 Commands 或 Queries。
• Commands/Queries 的结果被转换为 Responses，促进架构一致性。

简化示例：
public record CreatePersonRequest(string Name, int Age);
public record CreatePersonResponse(Guid Id, string Name, int Age);

创建新的 API

使用 Lino 的 CLI 创建一个端点非常简单：

lino new api

交互式向导将会提示：

• 服务 – 将在哪个服务中创建 API。
• 模块 – 服务的模块（如适用）。
• 实体 – 与端点关联的实体。
• API 名称 – 通常与操作动词保持一致（例如：CreatePerson）。
• 操作类型 - POST、PUT、PATCH、DELETE 或 GET。
• 路由 - 路由模式（例如：/people/{id}）。

示例：

当创建一个与实体 Person 关联的名为 CreatePerson 的 POST API 时，CLI 会自动生成：

• 带有 HTTP 映射的端点。
• 请求/响应 DTO。
• 用于 OpenAPI 集成和版本控制的扩展。
• 为其他服务内部调用准备的类型化 HttpClient。

生成的结构：

MyApp/
└── src/
    ├── Services/
    │   └── MyService/
    │       └── Presentation.API/
    │           ├── MyApp.MyService.Presentation.API.csproj
    │           └── Endpoints/
    │               └── People/
    │                   └── CreatePerson/
    │                       ├── CreatePersonEndpoint.cs
    │                       ├── CreatePersonExtensions.cs
    │                       ├── CreatePersonRequest.cs
    │                       └── CreatePersonResponse.cs
    └── Integrations/
        └── MyService/
            └── Http/
                ├── Contracts/
                │   └── Apis/
                │       └── People/
                │           ├── IPersonHttpClient.cs
                │           └── CreatePerson/
                │               ├── CreatePersonRequest.cs
                │               └── CreatePersonResponse.cs
                └── Clients/
                    └── Apis/
                        └── PersonHttpClient.cs

使用 Source Generators 注册端点

Lino 消除了手动映射端点或在运行时大量使用 Reflection 的需求。
相反，它使用 Source Generators 在编译期间自动生成注册代码。

工作原理

对于每个创建的端点，生成器会生成类/部分类来调用：
MapGet、MapPost、MapPut、MapDelete 等。

这取代了在 Program.cs 中手动添加所有映射的需求。

优点：

• 编译时注册 → 避免运行时错误。
• 精简的 Program.cs → 减少手动配置表面。
• AOT 兼容 → 消除对 Reflection 的依赖。
• 集成文档 → 元数据（tags、summary、produces）与映射一起生成。

该模式确保在 Lino 中创建的 API：

• 自动生成文档
• 高性能
• 与框架的 CQRS 架构保持一致