（3226期）Node.js Project Architecture – AI 友好型 Node.js 工程架构规范

AI 友好型 Node.js 工程架构规范 Node.js 项目架构规范，通过强制小文件拆分（<400 行）和配置外置化，解决 AI 开发时代码上下文窗口消耗过快的问题，支持游戏、数据工具、API 服务等多种项目类型。 使用说明 核心定位 nodejs-project-arch 是一套面向 AI 辅助开发的 Node.js 工程架构规范，核心目标是通过严格的文件粒度控制和配置管理，最大化 AI 编码助手的有效工作轮次。 核心用法 文件拆分规则：单文件硬性上限 400 行（index.html 200 行，server.js 100 行），强制开发者按功能域拆分为模块化结构。后端采用 routes/（按领域路由）、services/（共享逻辑）、db.js（数据库层）三层架构；前端 HTML 仅保留骨架，JS/CSS 完全分离。 配置外置化：所有可调参数纳入 config.json，运行时加载并可通过 /api/config 端点暴露给前端。配套提供 routes/admin.js + admin.html 实现配置热重载、可视化编辑、备份回滚及基础运维监控。 项目类型适配：内置 6 类项目模板——H5 游戏（Canvas/Phaser）、数据工具（爬虫/调度）、内容平台、监控面板、API 服务、SDK 库，通过 references/ 目录引用对应细分规范。 显著优点 AI 效率倍增：将 3000 行文件（约 40K tokens/次读取）压缩至 200 行模块（约 2.7K tokens），上下文窗口利用率从 20% 降至 1.3%，理论有效交互轮次从 3-5 轮提升至 10-15 轮。 运维友好：标准化 admin 面板降低配置变更成本，热重载避免重启服务。 工程可维护性：强制模块化天然契合单一职责原则，降低技术债务累积速度。 局限性与风险 适用边界：主要针对 Express/Koa 类传统 Node.js 项目，对 Next.js/Nuxt 等全栈框架的文件结构约束可能冲突；未涉及 TypeScript、测试策略、CI/CD 等现代工程链。 安全风险：admin 路由仅依赖 x-admin-password 头部校验，无速率限制、无会话管理、无审计日志，生产环境极易遭受暴力破解和未授权配置篡改；config.json 明文存储且备份文件 .bak 残留敏感信息。 性能陷阱：fs.readFileSync 同步读取配置在高并发场景阻塞事件循环；配置全量暴露给前端可能泄露数据库连接串等敏感字段（虽有 delete safe.admin 过滤，但依赖人工维护白名单）。 适合人群 独立开发者/小团队快速搭建 MVP，追求 AI 编码效率最大化 遗留单体 Node.js 项目重构，需控制文件规模以接入 AI 辅助 教学场景演示模块化架构思想 生产环境建议 admin 面板必须叠加 JWT + RBAC、配置加密存储（如 AWS Secrets Manager）、接口限流、操作审计日志；敏感配置字段采用服务端注入而非前端暴露。 原始说明 Node.js project architecture standards for AI-assisted development. Enforces file splitting (<400 lines), config externalization, route modularization, and a...