开发 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}）。

示例：

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

• 包含 HTTP 映射的端点。
• Request/Response DTO。
• 用于 OpenAPI 集成和版本控制的扩展。

生成的结构：

MyApp/
└── src/
    └── Services/
        └── MyService/
            └── Api/
                └── MyApp.MyService.Api.csproj
                    └── Endpoints/
                        └── People/
                            └── CreatePerson/
                                ├── CreatePersonEndpoint.cs
                                ├── CreatePersonExtensions.cs
                                ├── CreatePersonRequest.cs
                                └── CreatePersonResponse.cs

在包含 Web Blazor 应用的项目中，Lino 会自动生成消费 API 所需的相关产物。
这包括共享契约（Request 和 Response/DTO）、客户端接口以及用于 HTTP 调用的标准实现，使 Blazor 能以简单、类型安全且一致的方式使用这些 API。

MyApp/
└── src/
    └── Services/
        └── MyService/
            └── Api/
                ├── MyApp.MyService.Api.Contracts.csproj
                │   └── Features/
                │       └── People/
                │           ├── CreatePerson/
                │           │   ├── CreatePersonRequest.cs
                │           │   └── CreatePersonResponse.cs
                │           └── IPersonApiClient.cs
                └── MyApp.MyService.Api.Client.csproj
                    └── Features/
                        └── PersonApiClient.cs

使用 Source Generators 注册端点

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

工作原理

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

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

优点：

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

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

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