hexagonal-architecture
Use when isolating domain logic from frameworks, UI, and databases through ports and adapters. Do not use when the domain is trivial or the project is a thin framework wrapper.
- License 许可
- MIT
- 最近更新
- 2026-10-08
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- hexagonal-architecture
- license
- MIT
- metadata
- { "owner": "Harley Bartles", "status": "active", "use_when": [ "isolating domain logic from frameworks, UI, and databases through ports and adapters" ], "source-id": "hexagonal-architecture", "source-path": "skills/hexagonal-architecture/SKILL.md", "do_not_use_when": [ "the domain is trivial or the project is a thin framework wrapper" ], "provenance-name": "Hexagonal Architecture first-party skill", "source-category": "first_party" }
- description
- Use when isolating domain logic from frameworks, UI, and databases through ports and adapters. Do not use when the domain is trivial or the project is a thin framework wrapper.
02 资源文件 5
- 参考文档agents/openai.yaml601 B
- 资产文件assets/authority/authority.yaml997 B
- 资产文件assets/authority/CITATIONS.md1.1 KB
- 资产文件assets/authority/source-map.yaml418 B
- 参考文档references/operational-guidance.md1.7 KB
03 SKILL.md 正文
Hexagonal Architecture
Overview
Place domain logic at the center of the application and connect it to the outside world through explicit ports and adapters, so the core remains framework-agnostic.
When to Use
- The application must stay independent of databases, web frameworks, messaging systems, and external APIs.
- You need to test business rules with fake or in-memory adapters instead of real infrastructure.
- You want to swap a primary actor such as a UI, CLI, or test harness, or a secondary actor such as a database or service, without touching domain code.
- Do not use when the domain is trivial or the project is a thin framework wrapper.
Core Pattern
Define ports as interfaces the domain needs to interact with the outside world. Implement each port with one or more adapters:
- Primary (driving) adapters call the domain: REST controllers, CLI handlers, event consumers, and test fixtures.
- Secondary (driven) adapters are called by the domain: repositories, notification services, and external APIs.
The domain declares what it needs; adapters satisfy those needs. Dependencies cross the port boundary only in the direction that leaves the domain untouched.
Common Mistakes
- Building adapters that bypass the ports and call domain objects directly. Fix by routing all outside interaction through the declared port interfaces.
- Allowing frameworks to leak into application or domain code. Keep framework-specific annotations, SDK types, and configuration in adapter implementations.
- Confusing hexagonal architecture with clean or onion architecture. All three isolate the domain; hexagonal emphasizes ports and adapters as the concrete integration mechanism, while clean adds a layered dependency rule and onion uses concentric layers with dependency inversion.
04 同仓库更多 Skills
writing
Use when drafting, revising, or reviewing prose for human readers and clarity, an authorised voice, or reader-fatigue concerns may interact.
writing-with-clarity
Use when drafting, revising, or reviewing prose intended for human readers, including documentation, README files, reports, explanations, UI copy, errors, comments, commit messages, and pull request text.
writing-style
Use when revising or reviewing human-facing prose against an authorised voice card or a contextual reader-fatigue profile.
skill
暂无简介
writing-skills
Use when creating new skills, editing existing skills, or verifying skills work before deployment.
writing-roadmaps
Use when a goal is too large for one writing-plans plan and requires a sequenced roadmap of consecutive plans.