后端微服务云原生【免费下载链接】midway A Node.js Serverless Framework for front-end/full-stack developers. Build the application for next decade. Works on AWS, Alibaba Cloud, Tencent Cloud and traditional VM/Container. Super easy integrate with React and Vue. 项目地址https://gitcode.com/gh_mirrors/mi/midway点击查看免费下载导读本指南面向在 Midway 开源仓库中工作的 AI 编码助手Agent与贡献者系统梳理该仓库的 OpenSpec 规格驱动开发Spec-Driven Development工作流、Lerna pnpm Workspace 的 Monorepo 工程结构以及代码、测试、文档与提交规范。读完本指南你将掌握何时必须先读规格、如何创建变更提案、如何按规范实施并归档变更的完整闭环并能以符合 Midway 官方约定的方式提交高质量贡献。仓库根目录的 AGENTS.md 是面向 AI 助手的工作守则它分为两部分一段由OPENSPEC:START/OPENSPEC:END包裹、可被openspec update自动刷新的托管指令块以及一段由人工维护的仓库指南。前者指向 openspec/AGENTS.md 获取 OpenSpec 的完整玩法后者则浓缩了 Midway v4 的工程常识。本指南将二者合并展开并辅以仓库源码佐证。一、Midway v4 Monorepo 工程全景1.1 项目定位与技术栈Midway 是一个面向云端一体化front-end/full-stack应用开发的 Node.js 框架。当前仓库是 Midway v4 的 Monorepo核心工程事实如下以 package.json、lerna.json、tsconfig.json 为准包管理pnpm 9的 workspace由 Lerna 9 统一编排根 lerna.json 中npmClient: pnpm当前版本4.2.3语言与构建TypeScript 5.6.3使用tsc构建不依赖 webpack/rollupmodule: NodeNext、target: ES2022启用experimentalDecorators与emitDecoratorMetadata以支撑装饰器生态测试Jest 29.7.0 ts-jest每个包独立配置jest.config.js代码规范mwtsMidway TypeScript Stylelint 与 fix 均通过 lerna 批量执行运行时要求Node.js 20。1.2 目录布局packages/ # 71 个核心包与组件包独立 npm 包通过 DI 通信 packages-serverless # Serverless/FaaS 相关包 packages-resource/ # 资源测试组件 site/ # Docusaurus 文档站点docs 在 site/docs 下 benchmark/ # 性能基准 scripts/ # 构建与发布脚本 openspec/ # OpenSpec 规格目录specs/changes/archive从源码结构看IoC 容器的核心实现位于 packages/core包括MidwayContainer、DecoratorManager、MetadataManager等组件包如midwayjs/web、midwayjs/typeorm各自独立发布通过依赖注入互相协作——这正是仓库指南中每个组件是独立 npm 包可通过 DI 通信的落地形态。二、OpenSpec规格驱动开发的基石2.1 托管指令块与触发时机根 AGENTS.md 的托管块要求当请求涉及以下场景时必须先打开/openspec/AGENTS.md获取权威规格提及规划或提案proposal、spec、change、plan等关键词引入新能力、破坏性变更、架构调整或大型性能/安全工作请求听起来含糊不清需要在编码前确认权威规格。通过/openspec/AGENTS.md可以学到三件事如何创建与应用变更提案、规格的格式与约定、项目结构与指南。托管块必须保留以便openspec update刷新指令。2.2 三阶段工作流openspec/AGENTS.md 将整个开发流程划分为三个阶段阶段核心产物说明Stage 1: Creating Changesproposal.md、tasks.md、可选design.md、spec deltas新增能力、破坏性变更、架构调整、性能优化、安全模式变更都需先提案Stage 2: Implementing Changes按tasks.md顺序完成实现逐个完成任务并勾选清单提案评审通过前不得开始实现Stage 3: Archiving Changes归档目录 规格同步部署后单独 PR 归档更新specs/并重新验证判断是否需要提案的决策树New request? ├─ Bug fix restoring spec behavior? → 直接修复 ├─ Typo/format/comment? → 直接修复 ├─ 新功能/新能力? → 创建提案 ├─ 破坏性变更? → 创建提案 ├─ 架构变更? → 创建提案 └─ 不明确? → 创建提案更安全2.3 CLI 命令速查# 必备命令 openspec list # 列出活跃变更 openspec list --specs # 列出规格 openspec show [item] # 查看变更或规格详情 openspec validate [item] # 校验变更或规格 openspec archive change-id [--yes|-y] # 部署后归档--yes 用于非交互 # 项目管理 openspec init [path] # 初始化 OpenSpec openspec update [path] # 更新指令文件 # 交互模式 openspec show # 交互选择 openspec validate # 批量校验 # 调试 openspec show [change] --json --deltas-only openspec validate [change] --strict --no-interactive常用命令标志--json机器可读输出、--type change|spec消歧、--strict全面校验、--no-interactive禁用交互提示、--skip-specs归档时不更新规格、--yes/-y跳过确认。2.4 搜索与上下文清单动手前先按清单确认上下文阅读specs/[capability]/spec.md中相关规格检查changes/中待处理变更是否存在冲突阅读 openspec/project.md 了解约定运行openspec list查看活跃变更、openspec list --specs查看已有能力全文本搜索推荐用 ripgreprg -n Requirement:|Scenario: openspec/specs。三、创建变更提案从 proposal 到 delta3.1 目录结构与命名变更目录位于openspec/changes/change-id/。change-id必须是kebab-case、动词开头add-、update-、remove-、refactor-且全局唯一若被占用追加-2、-3等后缀。每个变更目录下可包含openspec/changes/[change-name]/ ├── proposal.md # Why, What, Impact ├── tasks.md # 实施清单 ├── design.md # 技术决策可选满足特定条件才创建 └── specs/ # delta 变更 └── [capability]/ └── spec.md # ADDED/MODIFIED/REMOVED/RENAMED仓库中 openspec/changes 现存多个处于提案阶段的能力变更例如add-graphql-component、add-mikro7-component、add-sse-ai-sdk-forwarding、add-swagger-validation-dto-reuse等可作为命名与组织方式的实际参照。3.2 proposal.md 模板# Change: [变更简述] ## Why [1-2 句话说明问题/机会] ## What Changes - [变更列表] - [破坏性变更用 **BREAKING** 标注] ## Impact - Affected specs: [受影响能力列表] - Affected code: [关键文件/系统]3.3 spec delta 模板## ADDED Requirements ### Requirement: New Feature The system SHALL provide... #### Scenario: Success case - **WHEN** user performs action - **THEN** expected result ## MODIFIED Requirements ### Requirement: Existing Feature [完整修改后的需求] ## REMOVED Requirements ### Requirement: Old Feature **Reason**: [删除原因] **Migration**: [迁移方式]一个变更若影响多个能力需在每个受影响的changes/[change-id]/specs/capability/spec.md下分别创建 delta 文件。3.4 tasks.md 模板## 1. Implementation - [ ] 1.1 Create database schema - [ ] 1.2 Implement API endpoint - [ ] 1.3 Add frontend component - [ ] 1.4 Write tests3.5 design.md何时需要仅在以下情况创建design.md否则省略跨模块/跨服务的横切变更或新架构模式新增外部依赖或重大数据模型变更涉及安全、性能或迁移复杂性存在需要在编码前消歧的技术决策。其骨架为Context→Goals / Non-Goals→Decisions含 Alternatives considered→Risks / Trade-offs→Migration Plan→Open Questions。四、Spec 文件格式的严格约定4.1 Scenario 格式关键必须使用四级标题#### Scenario:每个需求至少一个场景#### Scenario: User login success - **WHEN** valid credentials provided - **THEN** return JWT token以下写法均错误- **Scenario: User login** ❌ **Scenario**: User login ❌ ### Scenario: User login ❌4.2 需求措辞规范需求必须使用SHALL/MUSTshould/may仅在有意表达非规范语义时使用。4.3 Delta 操作语义## ADDED Requirements新增能力要求可独立成条## MODIFIED Requirements修改已有需求的行为/范围/验收标准。必须粘贴完整的新版需求标题 全部场景归档器会用你提供的内容整体替换原需求部分 delta 会丢失既有细节## REMOVED Requirements废弃特性需注明原因与迁移方式## RENAMED Requirements仅改名。格式为- FROM: \### Requirement: Login→- TO: ### Requirement: User Authentication若同时改行为用 RENAMED改名 MODIFIED改内容组合。常见坑用 MODIFIED 添加新关注点时没有包含旧文本导致归档时丢失细节。如果你不是在显式修改既有需求应优先在 ADDED 下新增一条需求。4.4 常见错误排查报错排查方向Change must have at least one delta检查changes/[name]/specs/存在且含.md确认文件带## ADDED Requirements等操作前缀Requirement must have at least one scenario检查场景使用#### Scenario:格式四级标题不要用列表或加粗场景静默解析失败格式必须精确为#### Scenario: Name用openspec show [change] --json --deltas-only调试校验时始终使用严格模式openspec validate [change] --strict --no-interactive。五、仓库代码规范测试、Lint 与注释根 AGENTS.md 的 Code rules 给出四条铁律与 openspec/project.md 的约定完全一致每个组件都是独立 npm 包通过 DI 通信验证于 packages 下 71 个独立包结构新增/修改组件必须包含测试在对应包内运行npm run test。仓库根 package.json 提供npm run testlerna 批量跑全部包与npm run cov覆盖率lerna run cov --concurrency 2 --stream两个入口使用mwts做 lintnpm run lint检查、npm run lint:fix自动修复。根 package.json 中的实现为lerna exec --ignore midwayjs/version -- mwts check/fix另外还有npm run lint:cyclemadge 循环依赖检查排除midwayjs/version、midwayjs/faas-typings等特定包为函数/类/接口/枚举添加有意义的注释。提交前需重新运行相关 lint 命令将必要的 lint-fix 输出保留在补丁中而不是随意回退——这与lint:cycle等 CI 门槛相呼应。六、文档规范Docusaurus 与初学者优先6.1 文档位置与风格当前文档位于site/docsDocusaurus 站点另有site/versioned_docs承载历史版本。撰写文档时需匹配现有风格、语气与结构。6.2 依赖安装的双形态展示组件文档必须同时给出bashnpm与JSONpackage.json两种安装形式例如npm i midwayjs/xxx --save{ dependencies: { midwayjs/xxx: ^4.0.0 } }6.3 组件文档写作顺序文档变更不需要构建检查Doc changes do not require a build check但要求对初学者友好遵循渐进式教程而非API 罗列先说清楚该组件解决什么问题、何时使用、最简单的可用路径再深入高级用法、配置与扩展点。七、实用技巧与提交流程7.1 高效命令定向跑测试pnpm -C package test在根目录直接对单个包执行避免全仓扫描全局测试npm run test经 lerna 分发保持模式一致变更尽量对齐目标包中既有模式。7.2 提交信息规范PR 标题必须使用标准 commit 格式如feat: xxx、fix: xxx。这与 openspec/project.md 中列出的 conventional commits 约定一致feat:、fix:、docs:、refactor:、test:、chore:等发布与 changelog 均由 lerna 依据这些标签自动生成见根 lerna.json 的 changelog 配置。八、规格驱动的实战示例从提案到归档的完整闭环将以上规范串成一个可直接照做的 Happy Path 流程源自 openspec/AGENTS.md# 1) 探索当前状态 openspec spec list --long openspec list # 可选全文搜索 # rg -n Requirement:|Scenario: openspec/specs # 2) 选择变更 ID 并脚手架 CHANGEadd-two-factor-auth mkdir -p openspec/changes/$CHANGE/specs/auth printf ## Why\n...\n\n## What Changes\n- ...\n\n## Impact\n- ...\n openspec/changes/$CHANGE/proposal.md printf ## 1. Implementation\n- [ ] 1.1 ...\n openspec/changes/$CHANGE/tasks.md # 3) 添加 delta示例 cat openspec/changes/$CHANGE/specs/auth/spec.md EOF ## ADDED Requirements ### Requirement: Two-Factor Authentication Users MUST provide a second factor during login. #### Scenario: OTP required - **WHEN** valid credentials are provided - **THEN** an OTP challenge is required EOF # 4) 校验 openspec validate $CHANGE --strict --no-interactive多能力变更示例add-2fa-notify可同时在specs/auth/spec.md与specs/notifications/spec.md下各写一条 ADDED 需求。九、规格的维护原则与归档9.1 状态语义changes/已提案、尚未构建specs/已构建并部署当前真相archive/已完成变更。一句话总结核心原则Specs are truth. Changes are proposals. Keep them in sync.规格是事实变更是提案二者必须保持同步。9.2 归档流程部署后创建单独 PR将changes/[name]/移入changes/archive/YYYY-MM-DD-[name]/若能力有变化则更新specs/纯工具型变更用openspec archive change-id --skip-specs --yes务必显式传 change ID最后运行openspec validate --strict --no-interactive确认归档后的变更通过校验。9.3 变更冲突与错误恢复变更冲突openspec list查看活跃变更 → 检查重叠规格 → 与变更负责人协调 → 考虑合并提案校验失败加--strict重跑 → 查看 JSON 输出细节 → 核对 spec 文件格式 → 确认场景格式正确上下文缺失先读 openspec/project.md → 查看相关规格 → 翻阅近期归档 → 必要时澄清。十、能力命名与最佳实践能力命名动词-名词结构如user-auth、payment-capture单一职责遵循10 分钟可理解原则——描述中出现 AND 就该拆分变更 ID 命名kebab-case、简短描述性、动词开头全局唯一简单优先默认新代码 100 行单文件实现优先除非有明确理由否则避免引入框架选择成熟稳妥的模式复杂性触发条件只有出现性能数据证明当前方案太慢、具体的规模化需求如 1000 用户、100MB 数据、或多个已被验证需要抽象的用例时才允许增加复杂度引用规范代码位置用file.ts:42格式规格引用为specs/auth/spec.md关联变更与 PR 应给出链接。结语Midway 仓库为 AI 助手与人类贡献者建立了一套规格先行的协作契约根 AGENTS.md 负责触发路由openspec/AGENTS.md 定义了三阶段工作流与严格的文件格式openspec/project.md 沉淀了技术栈、架构模式与约束。对 Agent 而言正确姿势是遇规划先读规格、提案先过校验、实现照清单逐项勾选、文档遵循初学者优先、提交使用 conventional commits。这套流程保证了大规模 Monorepo 下每个变更都有据可依、可验证、可追溯——这既是 Midway 的工程纪律也是所有 AI 编码助手在本仓库工作的通用操作手册。赞分享后端微服务云原生【免费下载链接】midway A Node.js Serverless Framework for front-end/full-stack developers. Build the application for next decade. Works on AWS, Alibaba Cloud, Tencent Cloud and traditional VM/Container. Super easy integrate with React and Vue. 项目地址https://gitcode.com/gh_mirrors/mi/midway点击查看免费下载相关推荐使用 /openspec-apply 落地已批准的 OpenSpec 变更Midway 仓库的规范驱动开发实施指南使用 /openspec apply 落地已批准的 OpenSpec 变更Midway 仓库的规范驱动开发实施指南 本文围绕 Midway 仓库内置的 Cur后端微服务云原生VoltAgent 仓库开发指南从 AI Agent 协作规范到 Monorepo 验证工作流VoltAgent 仓库开发指南从 AI Agent 协作规范到 Monorepo 验证工作流 VoltAgent 是一个开源的 TypeScript AI人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音面向 AI Agent 的 Monorepo 工程协作指南解读 liam 仓库的 CLAUDE.md 与开发规范面向 AI Agent 的 Monorepo 工程协作指南解读 liam 仓库的 CLAUDE.md 与开发规范 liamliam hq/liam是一个能数据可视化数据库前端CLI上一篇Bevy组件系统终极指南构建可复用代码模块的完整开发模式下一篇实测MiMo-V2-Flash-Base性能在256K上下文下超越Kimi-K2的终极体验创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考