AGENT SKILL

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

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