【系统架构设计百科】六边形、洋葱与整洁架构：端口与适配器的统一视角

// internal/domain/order.go
package domain

import (
    "errors"
    "time"
)

type OrderStatus string

const (
    OrderStatusPending   OrderStatus = "pending"
    OrderStatusConfirmed OrderStatus = "confirmed"
    OrderStatusPaid      OrderStatus = "paid"
    OrderStatusCancelled OrderStatus = "cancelled"
)

type OrderItem struct {
    ProductID string
    Name      string
    Price     int64
    Quantity  int
}

type Order struct {
    ID         string
    CustomerID string
    Items      []OrderItem
    Status     OrderStatus
    TotalPrice int64
    CreatedAt  time.Time
    UpdatedAt  time.Time
}

func NewOrder(id, customerID string, items []OrderItem) (*Order, error) {
    if id == "" {
        return nil, errors.New("order id is required")
    }
    if customerID == "" {
        return nil, errors.New("customer id is required")
    }
    if len(items) == 0 {
        return nil, errors.New("order must have at least one item")
    }
    var total int64
    for _, item := range items {
        if item.Price <= 0 || item.Quantity <= 0 {
            return nil, errors.New("item price and quantity must be positive")
        }
        total += item.Price * int64(item.Quantity)
    }
    now := time.Now()
    return &Order{
        ID: id, CustomerID: customerID, Items: items,
        Status: OrderStatusPending, TotalPrice: total,
        CreatedAt: now, UpdatedAt: now,
    }, nil
}

func (o *Order) Confirm() error {
    if o.Status != OrderStatusPending {
        return ErrInvalidStatusTransition
    }
    o.Status = OrderStatusConfirmed
    o.UpdatedAt = time.Now()
    return nil
}

func (o *Order) MarkPaid() error {
    if o.Status != OrderStatusConfirmed {
        return ErrInvalidStatusTransition
    }
    o.Status = OrderStatusPaid
    o.UpdatedAt = time.Now()
    return nil
}

func (o *Order) Cancel() error {
    if o.Status == OrderStatusPaid {
        return ErrCannotCancelPaidOrder
    }
    if o.Status == OrderStatusCancelled {
        return ErrOrderAlreadyCancelled
    }
    o.Status = OrderStatusCancelled
    o.UpdatedAt = time.Now()
    return nil
}

// internal/domain/errors.go
package domain

import "errors"

var (
    ErrOrderNotFound           = errors.New("order not found")
    ErrInvalidStatusTransition = errors.New("invalid order status transition")
    ErrCannotCancelPaidOrder   = errors.New("cannot cancel a paid order")
    ErrOrderAlreadyCancelled   = errors.New("order is already cancelled")
)

// internal/port/driving.go
package port

import (
    "context"
    "order-service/internal/domain"
)

type OrderService interface {
    CreateOrder(ctx context.Context, customerID string, items []domain.OrderItem) (*domain.Order, error)
    GetOrder(ctx context.Context, orderID string) (*domain.Order, error)
    ConfirmOrder(ctx context.Context, orderID string) error
    CancelOrder(ctx context.Context, orderID string) error
}

// internal/port/driven.go
package port

import (
    "context"
    "order-service/internal/domain"
)

type OrderRepository interface {
    Save(ctx context.Context, order *domain.Order) error
    FindByID(ctx context.Context, orderID string) (*domain.Order, error)
    Update(ctx context.Context, order *domain.Order) error
}

type EventPublisher interface {
    PublishOrderCreated(ctx context.Context, order *domain.Order) error
    PublishOrderCancelled(ctx context.Context, orderID string) error
}

// internal/app/order_service.go
package app

import (
    "context"
    "fmt"
    "order-service/internal/domain"
    "order-service/internal/port"

    "github.com/google/uuid"
)

type orderService struct {
    repo      port.OrderRepository
    publisher port.EventPublisher
}

func NewOrderService(repo port.OrderRepository, pub port.EventPublisher) port.OrderService {
    return &orderService{repo: repo, publisher: pub}
}

func (s *orderService) CreateOrder(ctx context.Context, customerID string, items []domain.OrderItem) (*domain.Order, error) {
    order, err := domain.NewOrder(uuid.New().String(), customerID, items)
    if err != nil {
        return nil, fmt.Errorf("create order: %w", err)
    }
    if err := s.repo.Save(ctx, order); err != nil {
        return nil, fmt.Errorf("save order: %w", err)
    }
    _ = s.publisher.PublishOrderCreated(ctx, order)
    return order, nil
}

func (s *orderService) GetOrder(ctx context.Context, orderID string) (*domain.Order, error) {
    return s.repo.FindByID(ctx, orderID)
}

func (s *orderService) ConfirmOrder(ctx context.Context, orderID string) error {
    order, err := s.repo.FindByID(ctx, orderID)
    if err != nil {
        return fmt.Errorf("find order: %w", err)
    }
    if err := order.Confirm(); err != nil {
        return fmt.Errorf("confirm order: %w", err)
    }
    return s.repo.Update(ctx, order)
}

func (s *orderService) CancelOrder(ctx context.Context, orderID string) error {
    order, err := s.repo.FindByID(ctx, orderID)
    if err != nil {
        return fmt.Errorf("find order: %w", err)
    }
    if err := order.Cancel(); err != nil {
        return fmt.Errorf("cancel order: %w", err)
    }
    if err := s.repo.Update(ctx, order); err != nil {
        return fmt.Errorf("update order: %w", err)
    }
    _ = s.publisher.PublishOrderCancelled(ctx, orderID)
    return nil
}

// internal/adapter/driving/http/handler.go
package http

import (
    "encoding/json"
    "errors"
    "net/http"
    "order-service/internal/domain"
    "order-service/internal/port"
)

type OrderHandler struct {
    service port.OrderService
}

func NewOrderHandler(svc port.OrderService) *OrderHandler {
    return &OrderHandler{service: svc}
}

func (h *OrderHandler) RegisterRoutes(mux *http.ServeMux) {
    mux.HandleFunc("POST /orders", h.CreateOrder)
    mux.HandleFunc("GET /orders/{id}", h.GetOrder)
    mux.HandleFunc("POST /orders/{id}/confirm", h.ConfirmOrder)
    mux.HandleFunc("POST /orders/{id}/cancel", h.CancelOrder)
}

func (h *OrderHandler) CreateOrder(w http.ResponseWriter, r *http.Request) {
    var req struct {
        CustomerID string             `json:"customer_id"`
        Items      []domain.OrderItem `json:"items"`
    }
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        writeError(w, http.StatusBadRequest, "invalid request body")
        return
    }
    order, err := h.service.CreateOrder(r.Context(), req.CustomerID, req.Items)
    if err != nil {
        writeError(w, http.StatusInternalServerError, err.Error())
        return
    }
    writeJSON(w, http.StatusCreated, order)
}

func (h *OrderHandler) GetOrder(w http.ResponseWriter, r *http.Request) {
    order, err := h.service.GetOrder(r.Context(), r.PathValue("id"))
    if err != nil {
        if errors.Is(err, domain.ErrOrderNotFound) {
            writeError(w, http.StatusNotFound, "order not found")
            return
        }
        writeError(w, http.StatusInternalServerError, err.Error())
        return
    }
    writeJSON(w, http.StatusOK, order)
}

func (h *OrderHandler) ConfirmOrder(w http.ResponseWriter, r *http.Request) {
    if err := h.service.ConfirmOrder(r.Context(), r.PathValue("id")); err != nil {
        writeError(w, http.StatusInternalServerError, err.Error())
        return
    }
    w.WriteHeader(http.StatusNoContent)
}

func (h *OrderHandler) CancelOrder(w http.ResponseWriter, r *http.Request) {
    if err := h.service.CancelOrder(r.Context(), r.PathValue("id")); err != nil {
        writeError(w, http.StatusInternalServerError, err.Error())
        return
    }
    w.WriteHeader(http.StatusNoContent)
}

func writeJSON(w http.ResponseWriter, status int, data interface{}) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(status)
    json.NewEncoder(w).Encode(data)
}

func writeError(w http.ResponseWriter, status int, msg string) {
    writeJSON(w, status, map[string]string{"error": msg})
}

// internal/adapter/driven/postgres/order_repo.go
package postgres

import (
    "context"
    "database/sql"
    "encoding/json"
    "fmt"
    "order-service/internal/domain"
)

type OrderRepository struct {
    db *sql.DB
}

func NewOrderRepository(db *sql.DB) *OrderRepository {
    return &OrderRepository{db: db}
}

func (r *OrderRepository) Save(ctx context.Context, order *domain.Order) error {
    itemsJSON, err := json.Marshal(order.Items)
    if err != nil {
        return fmt.Errorf("marshal items: %w", err)
    }
    _, err = r.db.ExecContext(ctx,
        "INSERT INTO orders (id, customer_id, items, status, total_price, created_at, updated_at) VALUES ($1,$2,$3,$4,$5,$6,$7)",
        order.ID, order.CustomerID, itemsJSON,
        string(order.Status), order.TotalPrice, order.CreatedAt, order.UpdatedAt)
    return err
}

func (r *OrderRepository) FindByID(ctx context.Context, orderID string) (*domain.Order, error) {
    var o domain.Order
    var status string
    var itemsJSON []byte
    err := r.db.QueryRowContext(ctx,
        "SELECT id, customer_id, items, status, total_price, created_at, updated_at FROM orders WHERE id = $1",
        orderID).Scan(&o.ID, &o.CustomerID, &itemsJSON, &status, &o.TotalPrice, &o.CreatedAt, &o.UpdatedAt)
    if err == sql.ErrNoRows {
        return nil, domain.ErrOrderNotFound
    }
    if err != nil {
        return nil, fmt.Errorf("query order: %w", err)
    }
    o.Status = domain.OrderStatus(status)
    if err := json.Unmarshal(itemsJSON, &o.Items); err != nil {
        return nil, fmt.Errorf("unmarshal items: %w", err)
    }
    return &o, nil
}

func (r *OrderRepository) Update(ctx context.Context, order *domain.Order) error {
    result, err := r.db.ExecContext(ctx,
        "UPDATE orders SET status = $1, updated_at = $2 WHERE id = $3",
        string(order.Status), order.UpdatedAt, order.ID)
    if err != nil {
        return fmt.Errorf("update order: %w", err)
    }
    rows, _ := result.RowsAffected()
    if rows == 0 {
        return domain.ErrOrderNotFound
    }
    return nil
}

// cmd/server/main.go
package main

import (
    "database/sql"
    "log"
    "net/http"

    "order-service/internal/adapter/driven/postgres"
    httpAdapter "order-service/internal/adapter/driving/http"
    "order-service/internal/app"

    _ "github.com/lib/pq"
)

func main() {
    db, err := sql.Open("postgres",
        "postgres://user:pass@localhost:5432/orders?sslmode=disable")
    if err != nil {
        log.Fatalf("connect db: %v", err)
    }
    defer db.Close()

    repo := postgres.NewOrderRepository(db)
    svc := app.NewOrderService(repo, &noopPublisher{})

    handler := httpAdapter.NewOrderHandler(svc)
    mux := http.NewServeMux()
    handler.RegisterRoutes(mux)
    log.Fatal(http.ListenAndServe(":8080", mux))
}

// domain/model/Order.java
package com.example.order.domain.model;

import com.example.order.domain.exception.InvalidStatusTransitionException;
import java.time.Instant;
import java.util.List;

public class Order {
    private final String id;
    private final String customerId;
    private final List<OrderItem> items;
    private OrderStatus status;
    private final long totalPrice;
    private final Instant createdAt;
    private Instant updatedAt;

    private Order(String id, String customerId, List<OrderItem> items,
                  long totalPrice, Instant createdAt) {
        this.id = id;
        this.customerId = customerId;
        this.items = List.copyOf(items);
        this.status = OrderStatus.PENDING;
        this.totalPrice = totalPrice;
        this.createdAt = createdAt;
        this.updatedAt = createdAt;
    }

    public static Order create(String id, String customerId, List<OrderItem> items) {
        if (id == null || id.isBlank())
            throw new IllegalArgumentException("Order ID is required");
        if (items == null || items.isEmpty())
            throw new IllegalArgumentException("Order must have at least one item");
        long total = items.stream()
                .mapToLong(i -> i.price() * i.quantity()).sum();
        return new Order(id, customerId, items, total, Instant.now());
    }

    public void confirm() {
        if (this.status != OrderStatus.PENDING)
            throw new InvalidStatusTransitionException(this.status, OrderStatus.CONFIRMED);
        this.status = OrderStatus.CONFIRMED;
        this.updatedAt = Instant.now();
    }

    public void cancel() {
        if (this.status == OrderStatus.PAID)
            throw new InvalidStatusTransitionException(this.status, OrderStatus.CANCELLED);
        if (this.status == OrderStatus.CANCELLED)
            throw new InvalidStatusTransitionException(this.status, OrderStatus.CANCELLED);
        this.status = OrderStatus.CANCELLED;
        this.updatedAt = Instant.now();
    }

    public String getId() { return id; }
    public String getCustomerId() { return customerId; }
    public List<OrderItem> getItems() { return items; }
    public OrderStatus getStatus() { return status; }
    public long getTotalPrice() { return totalPrice; }
    public Instant getCreatedAt() { return createdAt; }
    public Instant getUpdatedAt() { return updatedAt; }
}

// domain/model/OrderItem.java
package com.example.order.domain.model;

public record OrderItem(String productId, String name, long price, int quantity) {
    public OrderItem {
        if (price <= 0) throw new IllegalArgumentException("Price must be positive");
        if (quantity <= 0) throw new IllegalArgumentException("Quantity must be positive");
    }
}

// port/driving/OrderService.java
public interface OrderService {
    Order createOrder(String customerId, List<OrderItem> items);
    Order getOrder(String orderId);
    void confirmOrder(String orderId);
    void cancelOrder(String orderId);
}

// port/driven/OrderRepository.java
public interface OrderRepository {
    void save(Order order);
    Optional<Order> findById(String orderId);
    void update(Order order);
}

// application/OrderServiceImpl.java
package com.example.order.application;

import com.example.order.domain.exception.OrderNotFoundException;
import com.example.order.domain.model.*;
import com.example.order.port.driven.*;
import com.example.order.port.driving.OrderService;
import java.util.List;
import java.util.UUID;

public class OrderServiceImpl implements OrderService {
    private final OrderRepository repository;
    private final EventPublisher publisher;

    public OrderServiceImpl(OrderRepository repository, EventPublisher publisher) {
        this.repository = repository;
        this.publisher = publisher;
    }

    @Override
    public Order createOrder(String customerId, List<OrderItem> items) {
        Order order = Order.create(UUID.randomUUID().toString(), customerId, items);
        repository.save(order);
        publisher.publishOrderCreated(order);
        return order;
    }

    @Override
    public Order getOrder(String orderId) {
        return repository.findById(orderId)
                .orElseThrow(() -> new OrderNotFoundException(orderId));
    }

    @Override
    public void confirmOrder(String orderId) {
        Order order = getOrder(orderId);
        order.confirm();
        repository.update(order);
    }

    @Override
    public void cancelOrder(String orderId) {
        Order order = getOrder(orderId);
        order.cancel();
        repository.update(order);
        publisher.publishOrderCancelled(orderId);
    }
}

// adapter/driving/web/OrderController.java
@RestController
@RequestMapping("/orders")
public class OrderController {
    private final OrderService orderService;

    public OrderController(OrderService orderService) {
        this.orderService = orderService;
    }

    @PostMapping
    public ResponseEntity<Order> create(@RequestBody CreateOrderRequest req) {
        Order order = orderService.createOrder(req.customerId(), req.toItems());
        return ResponseEntity.status(HttpStatus.CREATED).body(order);
    }

    @GetMapping("/{id}")
    public ResponseEntity<Order> get(@PathVariable String id) {
        return ResponseEntity.ok(orderService.getOrder(id));
    }

    @PostMapping("/{id}/confirm")
    public ResponseEntity<Void> confirm(@PathVariable String id) {
        orderService.confirmOrder(id);
        return ResponseEntity.noContent().build();
    }

    @PostMapping("/{id}/cancel")
    public ResponseEntity<Void> cancel(@PathVariable String id) {
        orderService.cancelOrder(id);
        return ResponseEntity.noContent().build();
    }
}

// 显式 wire-up
@Configuration
public class OrderConfig {
    @Bean
    public OrderService orderService(OrderRepository repo, EventPublisher pub) {
        return new OrderServiceImpl(repo, pub);
    }
}

// ArchitectureTest.java
class ArchitectureTest {
    private static JavaClasses classes;

    @BeforeAll
    static void setup() {
        classes = new ClassFileImporter().importPackages("com.example.order");
    }

    @Test
    void domain_should_not_depend_on_adapter() {
        noClasses().that().resideInAPackage("..domain..")
                .should().dependOnClassesThat().resideInAPackage("..adapter..")
                .check(classes);
    }

    @Test
    void domain_should_not_depend_on_spring() {
        noClasses().that().resideInAPackage("..domain..")
                .should().dependOnClassesThat().resideInAPackage("org.springframework..")
                .check(classes);
    }

    @Test
    void application_should_not_depend_on_adapter() {
        noClasses().that().resideInAPackage("..application..")
                .should().dependOnClassesThat().resideInAPackage("..adapter..")
                .check(classes);
    }

    @Test
    void port_should_not_depend_on_adapter() {
        noClasses().that().resideInAPackage("..port..")
                .should().dependOnClassesThat().resideInAPackage("..adapter..")
                .check(classes);
    }
}

# .golangci.yml
linters:
  enable:
    - depguard
linters-settings:
  depguard:
    rules:
      domain-isolation:
        files:
          - "**/internal/domain/**"
        deny:
          - pkg: "order-service/internal/adapter"
            desc: "domain must not depend on adapter"
          - pkg: "database/sql"
            desc: "domain must not depend on database/sql"
      app-isolation:
        files:
          - "**/internal/app/**"
        deny:
          - pkg: "order-service/internal/adapter"
            desc: "app must not depend on adapter"

# .github/workflows/ci.yml
jobs:
  architecture-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: ArchUnit tests
        run: mvn test -Dtest=ArchitectureTest
      - name: Go architecture lint
        run: golangci-lint run --config .golangci.yml ./...

// 重构前的 PaymentService（简化示意）
@Service
public class PaymentService {
    @Autowired private AlipayClient alipayClient;
    @Autowired private WxPayClient wxPayClient;
    @Autowired private PaymentDao paymentDao;

    public PaymentResult pay(String orderId, BigDecimal amount, String channel) {
        PaymentRecord record = new PaymentRecord(orderId, amount, channel);
        paymentDao.insert(record);

        if ("ALIPAY".equals(channel)) {
            AlipayTradePayRequest req = new AlipayTradePayRequest();
            req.setBizContent("{\"out_trade_no\":\"" + orderId
                + "\",\"total_amount\":\"" + amount + "\"}");
            AlipayTradePayResponse resp = alipayClient.execute(req);
            record.setStatus(resp.isSuccess() ? "SUCCESS" : "FAILED");
            record.setTransactionId(resp.getTradeNo());
        } else if ("WXPAY".equals(channel)) {
            Map<String, String> data = Map.of(
                "out_trade_no", orderId,
                "total_fee", String.valueOf(amount.multiply(BigDecimal.valueOf(100)).intValue()));
            Map<String, String> result = wxPayClient.unifiedOrder(data);
            record.setStatus(
                "SUCCESS".equals(result.get("result_code")) ? "SUCCESS" : "FAILED");
            record.setTransactionId(result.get("transaction_id"));
        }
        paymentDao.update(record);
        return new PaymentResult(record.getStatus(), record.getTransactionId());
    }
}

public interface PaymentChannelPort {
    String channelName();
    PaymentChannelResult charge(String orderId, BigDecimal amount);
    PaymentChannelResult refund(String transactionId, BigDecimal amount);
}

@Component
public class AlipayChannelAdapter implements PaymentChannelPort {
    private final AlipayClient alipayClient;

    public AlipayChannelAdapter(AlipayClient alipayClient) {
        this.alipayClient = alipayClient;
    }

    @Override
    public String channelName() { return "ALIPAY"; }

    @Override
    public PaymentChannelResult charge(String orderId, BigDecimal amount) {
        AlipayTradePayRequest req = new AlipayTradePayRequest();
        req.setBizContent("{\"out_trade_no\":\"" + orderId
            + "\",\"total_amount\":\"" + amount + "\"}");
        try {
            AlipayTradePayResponse resp = alipayClient.execute(req);
            return resp.isSuccess()
                ? PaymentChannelResult.success(resp.getTradeNo())
                : PaymentChannelResult.failure(resp.getSubMsg());
        } catch (AlipayApiException e) {
            return PaymentChannelResult.failure(e.getMessage());
        }
    }

    @Override
    public PaymentChannelResult refund(String txnId, BigDecimal amount) {
        // 退款逻辑类似，调用 alipayClient 的退款接口
        return PaymentChannelResult.success(txnId);
    }
}

@Service
public class PaymentService {
    private final Map<String, PaymentChannelPort> channels;
    private final PaymentRepository paymentRepository;

    public PaymentService(List<PaymentChannelPort> channelList,
                          PaymentRepository paymentRepository) {
        this.channels = channelList.stream()
                .collect(Collectors.toMap(PaymentChannelPort::channelName, c -> c));
        this.paymentRepository = paymentRepository;
    }

    public PaymentResult pay(String orderId, BigDecimal amount, String channelName) {
        PaymentChannelPort channel = channels.get(channelName);
        if (channel == null) throw new UnsupportedChannelException(channelName);

        Payment payment = Payment.create(orderId, amount, channelName);
        paymentRepository.save(payment);

        PaymentChannelResult result = channel.charge(orderId, amount);
        payment.applyResult(result);
        paymentRepository.update(payment);
        return payment.toResult();
    }
}