陌讯skills聚合平台

acc-hexagonal-knowledge

📁 dykyi-roman/awesome-claude-code 📅 2 days ago
1
总安装量
1
周安装量
#51777
全站排名
安装命令
npx skills add https://github.com/dykyi-roman/awesome-claude-code --skill acc-hexagonal-knowledge

Agent 安装分布

opencode 1
claude-code 1

Skill 文档

Hexagonal Architecture Knowledge Base

Quick reference for Hexagonal Architecture (Ports & Adapters) patterns and PHP implementation guidelines.

Core Principles

Hexagonal Architecture Overview

                         ┌─────────────────────────────┐
                         │      PRIMARY ACTORS         │
                         │   (Users, External Apps)    │
                         └──────────────┬──────────────┘
                                        │
                         ┌──────────────▼──────────────┐
                         │     DRIVING ADAPTERS        │
                         │  (Controllers, CLI, GUI,    │
                         │   Message Consumers)        │
                         └──────────────┬──────────────┘
                                        │
              ┌─────────────────────────▼─────────────────────────┐
              │                  DRIVING PORTS                     │
              │              (Input Interfaces)                    │
              └─────────────────────────┬─────────────────────────┘
                                        │
              ┌─────────────────────────▼─────────────────────────┐
              │                                                    │
              │              APPLICATION CORE                      │
              │     ┌─────────────────────────────────┐           │
              │     │       APPLICATION LAYER         │           │
              │     │      (Use Cases, Services)      │           │
              │     └─────────────────┬───────────────┘           │
              │                       │                            │
              │     ┌─────────────────▼───────────────┐           │
              │     │         DOMAIN LAYER            │           │
              │     │  (Entities, Value Objects,      │           │
              │     │   Domain Services)              │           │
              │     └─────────────────────────────────┘           │
              │                                                    │
              └─────────────────────────┬─────────────────────────┘
                                        │
              ┌─────────────────────────▼─────────────────────────┐
              │                  DRIVEN PORTS                      │
              │            (Output Interfaces)                     │
              └─────────────────────────┬─────────────────────────┘
                                        │
                         ┌──────────────▼──────────────┐
                         │      DRIVEN ADAPTERS        │
                         │  (Repositories, External    │
                         │   APIs, Message Publishers) │
                         └──────────────┬──────────────┘
                                        │
                         ┌──────────────▼──────────────┐
                         │     SECONDARY ACTORS        │
                         │  (Database, External APIs,  │
                         │   Message Queues)           │
                         └─────────────────────────────┘

Core Rule: Application Core defines Ports. Adapters implement or use them.

Key Concepts

Concept Description Location
Port Interface defining how to interact with the core Application/Domain
Driving Port Input interface (how to use the application) Application layer
Driven Port Output interface (what the application needs) Application/Domain
Driving Adapter Implements input mechanism (HTTP, CLI) Infrastructure
Driven Adapter Implements external dependencies Infrastructure
Application Core Business logic, isolated from I/O Domain + Application

Quick Checklists

Driving Port Checklist

  • Interface in Application layer
  • Defines use case boundary
  • Uses domain/application types
  • No framework types
  • Single responsibility

Driven Port Checklist

  • Interface in Application/Domain layer
  • Abstracts external dependency
  • Uses domain types for return values
  • No implementation details in signature
  • Can have multiple adapters

Driving Adapter Checklist

  • Implements/calls driving port
  • Converts external format to domain format
  • No business logic
  • Framework code contained here
  • One adapter per delivery mechanism

Driven Adapter Checklist

  • Implements driven port interface
  • Converts domain format to external format
  • No business logic
  • Handles external errors
  • Easily replaceable

Common Violations Quick Reference

Violation Where to Look Severity
Core depends on adapter Domain importing Infrastructure Critical
Missing port abstraction Direct external service call Critical
Business logic in adapter if/switch in adapter Critical
Framework in core Symfony/Laravel in Domain Warning
Port with implementation details Interface using DB types Warning
Adapter without port Controller calling repository directly Warning

PHP 8.5 Hexagonal Patterns

Driving Port (Use Case Interface)

<?php

declare(strict_types=1);

namespace Application\Order\Port\Input;

use Application\Order\DTO\CreateOrderRequest;
use Application\Order\DTO\CreateOrderResponse;

interface CreateOrderUseCaseInterface
{
    public function execute(CreateOrderRequest $request): CreateOrderResponse;
}

Driven Port (Repository Interface)

<?php

declare(strict_types=1);

namespace Domain\Order\Port\Output;

use Domain\Order\Entity\Order;
use Domain\Order\ValueObject\OrderId;

interface OrderRepositoryInterface
{
    public function findById(OrderId $id): ?Order;
    public function save(Order $order): void;
    public function nextIdentity(): OrderId;
}

Driving Adapter (HTTP Controller)

<?php

declare(strict_types=1);

namespace Infrastructure\Http\Controller;

use Application\Order\Port\Input\CreateOrderUseCaseInterface;
use Application\Order\DTO\CreateOrderRequest;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;

final readonly class CreateOrderController
{
    public function __construct(
        private CreateOrderUseCaseInterface $createOrder
    ) {}

    public function __invoke(Request $request): JsonResponse
    {
        $dto = CreateOrderRequest::fromArray($request->toArray());

        $response = $this->createOrder->execute($dto);

        return new JsonResponse($response->toArray(), 201);
    }
}

Driven Adapter (Repository Implementation)

<?php

declare(strict_types=1);

namespace Infrastructure\Persistence\Doctrine;

use Domain\Order\Entity\Order;
use Domain\Order\Port\Output\OrderRepositoryInterface;
use Domain\Order\ValueObject\OrderId;
use Doctrine\ORM\EntityManagerInterface;

final readonly class DoctrineOrderRepository implements OrderRepositoryInterface
{
    public function __construct(
        private EntityManagerInterface $em
    ) {}

    public function findById(OrderId $id): ?Order
    {
        return $this->em->find(Order::class, $id->value);
    }

    public function save(Order $order): void
    {
        $this->em->persist($order);
        $this->em->flush();
    }

    public function nextIdentity(): OrderId
    {
        return OrderId::generate();
    }
}

References

For detailed information, load these reference files:

  • references/ports-patterns.md — Driving and Driven Port patterns
  • references/adapters-patterns.md — Adapter implementation patterns
  • references/testing-patterns.md — Testing strategies for hexagonal architecture
  • references/antipatterns.md — Common violations with detection patterns
GitHub 仓库 ↗ ← 返回陌讯 Skills 聚合平台
本页面由 陌讯 Skills 聚合平台 收录整理，数据定期更新。