CityServices PolyglotAspire 预改造评估样板的多语言微服务架构与手动运行全指南【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire本指南以仓库中 playground/aspireify-eval/polyglot/README.md 为骨架完整讲解这套由 Python、Go、C# 与 React 构成的多语言微服务应用 CityServices 的架构设计、配置方式与手动启动流程。该应用刻意保持 未 Aspire 化pre-aspirification状态是评测aspireify技能的标准化 before 样本读完本文你将掌握这类遗留多语言应用的依赖关系梳理、.env密钥管理、五窗口手动运维等实战方法并能对照评估细则理解其被 Aspire 改造后的目标形态。一、项目定位为评测aspireify技能而生的 前状态 样板该应用位于 playground/aspireify-eval/ 目录与另一套传统 .NET 解决方案dotnet-traditional/并列共同构成aspireify技能的评测样本。按父级 README 的说明这些应用被故意排除在 Aspire 体系之外——目录里没有解决方案文件.sln/.slnx没有 AppHost 项目四个服务通过硬编码 URL 互相调用全部配置散落在.env中。这正是真实世界遗留系统最常见的形态。评估流程本身非常简短见 playground/aspireify-eval/README.md进入polyglot/或dotnet-traditional/目录运行aspire init初始化让 Agent 执行aspireify技能完成改造依据 EVAL-RUBRIC.md 打分。一个关键设计约束是评估细则文件被刻意放在应用目录之外避免 Agent 在评测期间偷看预期结果。因此本文档所描述的运行方式代表手工运维的基线状态而评分细则则代表改造后的目标状态二者对照阅读即可理解一次完整的 Aspirification 旅程。二、架构总览四个语言、四种风格、零编排原文档用一张目录树清晰刻画了系统构成api-weather/ → Python FastAPI (port 8001), weather data with Redis caching api-geo/ → Go stdlib HTTP (port 8002), geocoding stub with external API key api-events/ → C# minimal API (port 8003), city events endpoint frontend/ → React Vite (port 5173), calls all three APIs directly .env → All config: Redis URL, API keys可以看到这是一个典型的 无中生有 的微服务拼盘api-weatherPython FastAPI负责天气数据带 Redis 缓存api-geoGo 标准库 HTTP 服务提供地理编码桩数据预留外部 API Keyapi-eventsC# 最小 API提供城市活动列表frontendReact Vite 前端直接调用上述三个后端.env承载全部配置Redis 地址、各类 API Key。整个仓库没有解决方案文件、没有 AppHost四个服务各自独立通过硬编码 URL 相互通信——这正是 Aspire 化之前最典型的痛点场景。三、四个服务的源码级解读3.1 api-weatherPython FastAPI Redis 缓存源码位于 api-weather/main.py其配置读取方式与缓存逻辑直接印证了架构说明redis_url os.environ.get(REDIS_URL, localhost:6379) weather_api_key os.environ.get(WEATHER_API_KEY, ) redis_host, redis_port redis_url.split(:) cache redis.Redis(hostredis_host, portint(redis_port), decode_responsesTrue)值得注意的实现细节REDIS_URL与WEATHER_API_KEY均通过os.environ.get读取且都带有默认值localhost:6379与空串意味着缺省环境下服务也能启动——这是桩数据优先的设计取向Redis连接把host:port字符串手动split(:)后拆开这种手工解析恰恰是 AspirewithReference想消除的样板代码/weather/{city}采用 cache-aside 模式先查weather:{city}缓存命中直接返回未命中则返回桩数据温度 72°F、多云、湿度 45%、source: stub并以 300 秒 TTL 写回 Redis/cities返回[seattle, new-york, san-francisco, chicago, austin]与前端城市下拉框完全一致/health返回{status: healthy, service: api-weather}。依赖清单见 requirements.txtfastapi0.115.0、uvicorn0.34.0、redis5.0.0、httpx0.28.0httpx 虽已引入但当前桩实现中尚未使用为后续接入真实外部天气 API 预留。3.2 api-geoGo 标准库 HTTP 服务源码位于 api-geo/main.go是四个服务中唯一不依赖第三方 Web 框架的port : os.Getenv(PORT) if port { port 8002 } apiKey : os.Getenv(GEOCODING_API_KEY)实现要点端口可注入PORT环境变量优先缺省回落到8002。这一点在评估细则中极为关键——Aspire 化时要求通过withHttpEndpoint({ env: PORT })注入端口见 EVAL-RUBRIC.md地理编码为桩数据/geocode/{city}无论城市为何一律返回西雅图的坐标lat: 47.6062, lng: -122.3321并通过APIKeySet: apiKey ! 暴露外部 Key 是否已配置的状态/health同样返回{status: healthy, service: api-geo}。go.mod 声明模块名为cityservices/api-geo要求 Go 1.23。3.3 api-eventsC# 最小 API源码位于 api-events/Program.cs目标框架为net10.0见 api-events.csproj。整个程序只有一个文件、三段路由/health→ 返回{ status healthy, service api-events }/events→ 返回内存中的 4 条活动数据含 Seattle 的 Aspire Community Standup、New York 的 .NET Conf Local 等/events/{city}→ 按城市过滤使用OrdinalIgnoreCase实现大小写不敏感匹配。值得留意的是当前 C# 服务尚未接入任何环境变量原文档明确写道 arent wired yet (C#, React)这是半成品状态的一部分也是 Aspire 化时需要通过AddProject建模并注入连接信息的目标对象。3.4 frontendReact Vite 前端源码位于 frontend/src/App.tsx最典型的问题就是硬编码后端地址// These would be injected by Aspire after aspirification const WEATHER_API import.meta.env.VITE_WEATHER_API_URL || http://localhost:8001; const GEO_API import.meta.env.VITE_GEO_API_URL || http://localhost:8002; const EVENTS_API import.meta.env.VITE_EVENTS_API_URL || http://localhost:8003;代码注释已经直白地预告了出路这些地址在 Aspire 化之后将被注入。组件逻辑本身很简单通过城市下拉框选择城市useEffect中并行请求三个后端接口分别渲染天气、位置与活动 JSON。工程配置方面依赖 React 19 Vite 6见 package.json开发服务器固定 5173 端口见 vite.config.ts。四、运行环境依赖原文档列出的前置依赖如下依赖版本要求用途.NET SDK10编译运行 api-eventsC# 最小 APINode.js20运行 Vite 开发服务器与前端构建Python3.12含 pip运行 api-weatherFastAPIGo1.23编译运行 api-geoRedis本地 6379 端口提供天气缓存与后续所有服务的依赖基础设施由于本文档的定位是Aspire 化之前的基线状态这些依赖全部需要手动安装配置待 Aspire 化完成后Redis 等基础设施将由 Aspire 以受管容器形式拉起开发机只需保留各语言运行时即可。五、配置说明.env变量一览原文档规定所有配置统一存放在应用根目录的.env文件中。需要特别说明的是该文件并未随仓库提交其中包含密钥属于典型的 gitignore 内容读者需依据下表自行创建变量用途是否机密REDIS_URLRedis 的 host:port供天气缓存使用否GEOCODING_API_KEY外部地理编码 API 密钥是WEATHER_API_KEY外部天气 API 密钥是OPENAI_API_KEYOpenAI API 密钥为未来的 advisor 功能预留是各语言读取方式各不相同Python 走os.environGo 走os.Getenv而 C# 与 React 尚未接线。这种每个服务各读各的、密钥明文躺在根目录的现状正是 Aspire 化时要用AddParameter(secret: true)与withReference彻底替代的痛点。六、无 Aspire 手动运行五个终端窗口的运维体操原文档给出了完整的六步启动流程全程需要5 个终端窗口外加一个运行中的 Redis。以下按原文档顺序完整保留并补充必要的说明。1. 启动基础设施终端 1docker run -d --name cityservices-redis \ -p 6379:6379 \ redis:7以redis:7镜像启动命名容器映射宿主机 6379 端口。若本机已有 Redis 实例监听 6379此步可跳过。2. 加载环境变量每个终端都要执行# In each terminal: export $(cat .env | xargs)注意每个终端窗口都需要执行一次因为环境变量按进程隔离。这是多窗口运维最易遗漏的一步——遗漏后 Python 服务会回落默认值而 Go 服务的GEOCODING_API_KEY将为空。3. 启动天气 API终端 2Pythoncd api-weather pip install -r requirements.txt uvicorn main:app --host 0.0.0.0 --port 8001按 requirements.txt 安装依赖后以 uvicorn 启动 FastAPI 应用监听 8001 端口。4. 启动地理 API终端 3Gocd api-geo PORT8002 go run .PORT显式传给 Go 服务缺省时 main.go 会回落到 8002。5. 启动活动 API终端 4C#cd api-events dotnet run --urls http://localhost:80036. 启动前端终端 5Reactcd frontend npm install npm run dev # Opens on http://localhost:5173至此五个服务全部就绪1 个基础设施 4 个应用进程分布在 5 个窗口里各管各的。任何一次端口冲突、环境变量遗漏或重启顺序错误都需要人工排查。七、验证清单如何确认四个服务协同正常原文档提供了一套完整的冒烟验证点逐项核对即可确认整条链路可用检查项URL预期结果前端http://localhost:5173显示 CityServices并呈现 Seattle 的天气、地理与活动数据天气接口http://localhost:8001/weather/seattle返回天气桩数据城市列表http://localhost:8001/cities返回城市列表地理接口http://localhost:8002/geocode/seattle返回 lat/lng 桩数据活动列表http://localhost:8003/events返回全部活动按城市活动http://localhost:8003/events/seattle返回 Seattle 活动健康检查各服务/health返回服务名与状态四个服务的/health均返回{status: healthy, service: 服务名}可在验证阶段快速定位故障服务。八、Aspire 化后的目标形态对照评估细则理解改造方向前文所有 痛点 在 EVAL-RUBRIC.md 的 polyglot 章节中都有对应的目标项。将其与本文档的 before 状态对照可以完整还原一次 Aspire 改造的蓝图编排形态采用 TypeScript AppHost 单文件模式apphost.ts因无.sln不启用项目模式并在仓库根目录生成 aspire.config.json 同级的配置四个服务分别以AddPythonApp、AddDockerfile/自定义、AddProject、AddViteApp/AddNpmApp建模Redis 使用addRedis类型化集成而非裸容器依赖排序后端waitForRedis前端waitFor全部后端服务替代现在靠人肉顺序启动的方式密钥迁移REDIS_URL改为withReference注入GEOCODING_API_KEY、WEATHER_API_KEY、OPENAI_API_KEY三个机密全部迁移为 secret 参数——.env文件在 Aspire 运行方式下不再需要通信注入前端不再硬编码 localhost后端地址由 Aspire 注入Go 服务通过withHttpEndpoint({ env: PORT })接收端口Python 服务通过 Aspire 获得 Redis 连接可观测性为 PythonFastAPI OTLP与 GoOTLP exporter建议接入 OpenTelemetryC# 服务单独评估是否需要完整 ServiceDefaults工程配置根目录补充package.jsontype: module start 脚本与tsconfig.json并依次执行aspire restore与npm install。这套对照清晰地说明本文档描述的手工运行方式不是终点而是改造的起点。当aspire start一键拉起全部服务、所有密钥由参数管理、所有地址自动注入时本文第五章 五窗口运维 的每一行命令都将成为历史。九、总结CityServices Polyglot 是一份精心设计的 反例四种语言、零编排、硬编码地址、明文密钥、五窗口手工启动——几乎集齐了遗留多语言微服务的所有典型问题。正因为如此它才是评测aspireify技能的理想样本改造前的问题足够真实改造后的评估点足够明确。读者既可以把它当作多语言微服务手工运维的练习场复现 README.md 中的六步流程也可以结合 EVAL-RUBRIC.md 推演一次完整的 Aspire 改造从而深刻理解从手工编排到声明式编排的价值所在。【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考