# Software Architecture > 面向质量的软件架构指导。当用户需要编写代码、设计架构、分析代码或进行任何与软件开发相关的工作时使用。触发词：软件架构、架构设计、Clean Architecture、DDD、领域驱动设计、代码规范、架构模式、software architecture - Skill: `kscz0000/software-architecture` (Agent Skill) - Install (CLI): `npx skillmds@latest add kscz0000/software-architecture` - Raw SKILL.md: https://api.skillmd.com/api/skills/kscz0000/software-architecture/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: kscz0000 (https://skillmd.com/u/kscz0000) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/kscz0000/software-architecture --- # 软件架构开发技能 本技能提供面向质量的软件开发与架构指导，基于 Clean Architecture 和领域驱动设计（DDD）原则。 ## 代码风格规范 ### 通用原则 - **提前返回模式**：尽可能使用提前返回代替嵌套条件，以提升可读性 - 通过创建可复用的函数和模块避免代码重复 - 将过长的组件和函数（超过 80 行代码）拆分为多个更小的组件和函数。如果无法在其他地方复用，保留在同一文件中。但如果文件超过 200 行代码，应拆分为多个文件 - 尽可能使用箭头函数代替函数声明 ### 最佳实践 #### 优先使用现有库 - **在编写自定义代码之前，务必先搜索现有解决方案** - 在 npm 中查找已有的库来解决问题 - 评估现有的服务/SaaS 方案 - 考虑使用第三方 API 实现通用功能 - 使用现有库而不是自己编写工具函数。例如，使用 `cockatiel` 而不是自己编写重试逻辑。 - **以下情况可以编写自定义代码：** - 领域特有的业务逻辑 - 有特殊要求的性能关键路径 - 外部依赖过于笨重时 - 需要完全控制的安全敏感代码 - 经过充分评估后现有方案均不满足需求 #### 架构与设计 - **Clean Architecture 与 DDD 原则：** - 遵循领域驱动设计和统一语言 - 将领域实体与基础设施关注点分离 - 保持业务逻辑独立于框架 - 清晰定义用例并保持隔离 - **命名规范：** - **避免**通用命名：`utils`、`helpers`、`common`、`shared` - **使用**领域特定命名：`OrderCalculator`、`UserAuthenticator`、`InvoiceGenerator` - 遵循限界上下文命名模式 - 每个模块应有单一且明确的职责 - **关注点分离：** - 不要将业务逻辑与 UI 组件混在一起 - 不要在控制器中编写数据库查询 - 维护上下文之间的清晰边界 - 确保职责的合理分离 #### 需要避免的反模式 - **NIH（非我发明）综合征：** - 不要在 Auth0/Supabase 存在的情况下自建认证系统 - 不要在 Redux/Zustand 可用的情况下自写状态管理 - 不要在成熟库可用的情况下自创表单验证 - **糟糕的架构选择：** - 将业务逻辑与 UI 组件混在一起 - 在控制器中直接写数据库查询 - 缺乏清晰的关注点分离 - **通用命名反模式：** - `utils.js` 里放了 50 个不相关的函数 - `helpers/misc.js` 成了万能垃圾桶 - `common/shared.js` 职责不明确 - 请记住：每一行自定义代码都是需要维护、测试和文档化的负债 #### 代码质量 - 使用类型化的 catch 块进行恰当的错误处理 - 将复杂逻辑拆分为更小的可复用函数 - 避免深层嵌套（最多 3 层） - 保持函数聚焦，尽量控制在 50 行以内 - 保持文件聚焦，尽量控制在 200 行代码以内 ## 适用场景 本技能适用于执行概述中描述的工作流程或操作。 ## 局限性 - 仅在任务明确匹配上述范围时使用本技能。 - 不要将输出视为环境特定验证、测试或专家评审的替代品。 - 如果缺少必要的输入、权限、安全边界或成功标准，请停下来请求澄清。