应用模型与架构

更新: 2026-10-16 15:20:09   字数: 0 字   时长: 0 分钟

AppHost 描述的这份结构在 Aspire 中称为应用模型（application model）。理解它的三个要素——资源、注解、关系——就能理解 Aspire 的大部分 API 设计。

应用模型是一张有向无环图

资源是节点，依赖是边。Aspire 按这张图来决定启动顺序、注入哪些配置、以及如何在仪表板上展示。

var builder = DistributedApplication.CreateBuilder(args);

var db = builder.AddPostgres("pg").AddDatabase("appdata");
var api = builder.AddProject<Projects.Api>("api").WithReference(db);
var web = builder.AddNpmApp("web", "../web").WithReference(api);

builder.Build().Run();

这段代码定义了三个资源与两条依赖边：web → api → db。

正因为是 DAG，Aspire 才能：

• 推导出 db 必须先于 api 启动，api 必须先于 web 启动。
• 只有 api 会拿到 db 的连接字符串，web 不会——服务只知道自己显式声明的依赖。
• 在仪表板上以正确的层级与连线展示整个系统。

注解（Annotations）

资源的元数据用注解表达。注解是实现 IResourceAnnotation 的强类型对象，例如「我要暴露一个 HTTP 端点」「这个资源要运行健康检查」。

// 这些 With 系列 API 本质上是往资源上挂注解
var api = builder.AddProject<Projects.Api>("api")
    .WithHttpEndpoint(targetPort: 8080)
    .WithHttpHealthCheck("/health");

您也可以挂自定义注解，供自己的发布器或工具链读取：

public sealed class TeamAnnotation(string team) : IResourceAnnotation
{
    public string Team { get; } = team;
}

builder.AddProject<Projects.Api>("api")
    .WithAnnotation(new TeamAnnotation("订单团队"));

读取注解：

var annotations = api.Resource.Annotations.OfType<TeamAnnotation>();

什么时候需要注解？

当您想让别人写的工具（发布器、自定义集成、治理脚本）识别某个资源上的额外信息时，注解是最合适的扩展点。

资源 API 模式

Aspire 的集成 API 遵循稳定的命名约定，记住模式就能猜到大部分方法名：

前缀	含义	示例
Add*	向模型添加资源	AddPostgres、AddProject、AddParameter
With*	为资源附加能力、配置或引用	WithReference、WithHttpEndpoint、WithDataVolume
On*	注册生命周期钩子	OnResourceReady、OnBeforeResourceStarted
PublishAs*	指定资源在发布/部署时的形态	PublishAsAzurePostgresFlexibleServer
As*	把资源转换/修饰为另一种资源	AsContainer、AsHttp2Service

命名空间

绝大多数 Add* 方法是 DistributedApplicationBuilder 上的扩展方法，由 Aspire.Hosting 及具体集成包的命名空间提供。缺少 using 时，IDE 通常会自动提示补全。

资源层级

资源可以形成父子层级。这是**表达「归属」**的方式：

builder.AddPostgres("pg")
    .AddDatabase("appdata")          // 逻辑数据库，归属 pg
    .WithParentRelationship(pg);     // 显式声明归属（可选）

worker.WithParentRelationship(api);  // 让 worker 显示为 api 的子资源

层级影响展示与命名，但不自动建立启动依赖——启动依赖请使用 WaitFor。

发布模型

同一个应用模型在发布时会被「翻译」成目标平台的产物：

本地（Run 模式）	发布（Publish 模式）
AddPostgres("pg") 启动容器	映射到 Azure Database for PostgreSQL 或 Kubernetes 中的容器
AddRedis("cache")	映射到 Azure Cache for Redis 或容器
AddProject<T>()	映射为容器镜像 + 部署定义
AddParameter("pwd")	映射为部署时的参数/机密输入

对应到 AppHost 代码：

var pg = builder.AddPostgres("pg")
    .PublishAsAzurePostgresFlexibleServer();   // 发布时替换为 Azure 托管服务

var db = pg.AddDatabase("appdata");

中间的产物是部署清单（manifest），由 aspire publish 生成，可作为 CI/CD 的输入。详见部署清单。

多语言架构

Aspire 的应用模型与语言无关。同一张图里可以容纳：

• .NET 项目（AddProject）
• Node.js / npm / Vite（AddNodeApp、AddNpmApp、AddViteApp）
• Python（AddPythonApp）
• Go、Java、Rust（对应集成包）
• 任意容器（AddContainer、AddDockerfile）
• 任意本机可执行文件（AddExecutable）

var db = builder.AddPostgres("db");

var api = builder.AddProject<Projects.Api>("api").WithReference(db);
var worker = builder.AddPythonApp("worker", "../worker", "main.py").WithReference(db);

builder.AddNpmApp("frontend", "../frontend").WithReference(api);

跨语言资源之间同样通过 WithReference 注入连接信息与服务发现配置——只要目标语言能读取环境变量即可。

一体化调试

多语言栈的日志、追踪会统一汇入 Aspire 仪表板。这意味着排查「Python worker 调用 .NET API 超时」这类问题时，您可以沿着一条分布式追踪从头看到尾。

下一步

• 资源模型
• 服务发现
• 部署清单