【系统架构设计百科】防腐层与开放主机服务：系统集成的 DDD 方案

// 新系统的领域模型——清晰、语义明确
public class Account {
    private AccountId id;
    private AccountHolder holder;
    private Money balance;
    private AccountStatus status; // ACTIVE, FROZEN, CLOSED
    private Currency currency;
}

{
  "ACCT_NO": "00123456789012",
  "CUST_CD": "C0001",
  "BAL_AMT": 1234500,
  "BAL_CCY": "156",
  "STAT_CD": "01",
  "ACCT_TYP": "SA",
  "LST_TXN_DT": "20250101",
  "BRN_CD": "001"
}

// ============ Adapter 层：负责网络通信 ============
public class CoreBankingAdapter {
    private final HttpClient httpClient;
    private final String baseUrl;

    public CoreBankingAdapter(HttpClient httpClient, String baseUrl) {
        this.httpClient = httpClient;
        this.baseUrl = baseUrl;
    }

    public CoreBankingAccountDto fetchAccount(String accountNumber) {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(baseUrl + "/accounts/" + accountNumber))
            .header("Content-Type", "application/json")
            .GET()
            .build();

        try {
            HttpResponse<String> response = httpClient.send(
                request, HttpResponse.BodyHandlers.ofString());

            if (response.statusCode() != 200) {
                throw new ExternalSystemException(
                    "核心银行系统返回错误: " + response.statusCode());
            }

            return objectMapper.readValue(
                response.body(), CoreBankingAccountDto.class);
        } catch (IOException | InterruptedException e) {
            throw new ExternalSystemException(
                "调用核心银行系统失败", e);
        }
    }
}

// ============ 外部系统的 DTO ============
public class CoreBankingAccountDto {
    @JsonProperty("ACCT_NO")
    private String accountNumber;
    @JsonProperty("CUST_CD")
    private String customerCode;
    @JsonProperty("BAL_AMT")
    private long balanceAmount; // 以分为单位
    @JsonProperty("BAL_CCY")
    private String balanceCurrency; // ISO 数字码
    @JsonProperty("STAT_CD")
    private String statusCode;
    @JsonProperty("LST_TXN_DT")
    private String lastTransactionDate; // yyyyMMdd
    // getter/setter 省略
}

// ============ Translator 层：负责模型转换 ============
public class AccountTranslator {

    private static final Map<String, AccountStatus> STATUS_MAP = Map.of(
        "01", AccountStatus.ACTIVE,
        "02", AccountStatus.FROZEN,
        "03", AccountStatus.CLOSED
    );

    private static final Map<String, Currency> CURRENCY_MAP = Map.of(
        "156", Currency.getInstance("CNY"),
        "840", Currency.getInstance("USD"),
        "978", Currency.getInstance("EUR")
    );

    public Account toDomain(CoreBankingAccountDto dto) {
        AccountStatus status = STATUS_MAP.get(dto.getStatusCode());
        if (status == null) {
            throw new TranslationException(
                "未知的账户状态码: " + dto.getStatusCode());
        }

        Currency currency = CURRENCY_MAP.get(dto.getBalanceCurrency());
        if (currency == null) {
            throw new TranslationException(
                "未知的币种代码: " + dto.getBalanceCurrency());
        }

        // 将"分"转换为"元"
        BigDecimal amount = BigDecimal.valueOf(dto.getBalanceAmount())
            .divide(BigDecimal.valueOf(100), 2, RoundingMode.HALF_UP);

        return Account.reconstitute(
            new AccountId(dto.getAccountNumber()),
            new AccountHolder(dto.getCustomerCode()),
            new Money(amount, currency),
            status
        );
    }
}

// ============ Facade 层：提供领域语言接口 ============
public class ExternalAccountService {
    private final CoreBankingAdapter adapter;
    private final AccountTranslator translator;

    public ExternalAccountService(CoreBankingAdapter adapter,
                                   AccountTranslator translator) {
        this.adapter = adapter;
        this.translator = translator;
    }

    /**
     * 查询外部账户信息，返回本域的 Account 领域对象。
     * 本域代码只与 ExternalAccountService 交互，
     * 不需要知道核心银行系统的存在。
     */
    public Account findAccount(AccountId accountId) {
        CoreBankingAccountDto dto = adapter.fetchAccount(
            accountId.value());
        return translator.toDomain(dto);
    }

    public boolean isAccountActive(AccountId accountId) {
        Account account = findAccount(accountId);
        return account.isActive();
    }
}

// adapter.go —— 网络通信层
type CoreBankingClient struct {
    baseURL    string
    httpClient *http.Client
}

type coreBankingAccountDTO struct {
    AccountNo   string `json:"ACCT_NO"`
    CustomerCode string `json:"CUST_CD"`
    BalanceAmt  int64  `json:"BAL_AMT"`
    BalanceCcy  string `json:"BAL_CCY"`
    StatusCode  string `json:"STAT_CD"`
}

func (c *CoreBankingClient) FetchAccount(ctx context.Context,
    accountNo string) (*coreBankingAccountDTO, error) {

    url := fmt.Sprintf("%s/accounts/%s", c.baseURL, accountNo)
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
    if err != nil {
        return nil, fmt.Errorf("构建请求失败: %w", err)
    }

    resp, err := c.httpClient.Do(req)
    if err != nil {
        return nil, fmt.Errorf("调用核心银行系统失败: %w", err)
    }
    defer resp.Body.Close()

    if resp.StatusCode != http.StatusOK {
        return nil, fmt.Errorf("核心银行系统返回错误: %d", resp.StatusCode)
    }

    var dto coreBankingAccountDTO
    if err := json.NewDecoder(resp.Body).Decode(&dto); err != nil {
        return nil, fmt.Errorf("解析响应失败: %w", err)
    }
    return &dto, nil
}

// translator.go —— 模型转换层
var statusMap = map[string]AccountStatus{
    "01": AccountStatusActive,
    "02": AccountStatusFrozen,
    "03": AccountStatusClosed,
}

var currencyMap = map[string]string{
    "156": "CNY",
    "840": "USD",
    "978": "EUR",
}

func translateAccount(dto *coreBankingAccountDTO) (*Account, error) {
    status, ok := statusMap[dto.StatusCode]
    if !ok {
        return nil, fmt.Errorf("未知的账户状态码: %s", dto.StatusCode)
    }

    currencyCode, ok := currencyMap[dto.BalanceCcy]
    if !ok {
        return nil, fmt.Errorf("未知的币种代码: %s", dto.BalanceCcy)
    }

    // 分 → 元
    amount := decimal.NewFromInt(dto.BalanceAmt).
        Div(decimal.NewFromInt(100))

    return &Account{
        ID:      AccountID(dto.AccountNo),
        Holder:  AccountHolder(dto.CustomerCode),
        Balance: NewMoney(amount, currencyCode),
        Status:  status,
    }, nil
}

// facade.go —— 领域语言接口
type ExternalAccountService struct {
    client     *CoreBankingClient
}

func (s *ExternalAccountService) FindAccount(ctx context.Context,
    id AccountID) (*Account, error) {

    dto, err := s.client.FetchAccount(ctx, string(id))
    if err != nil {
        return nil, fmt.Errorf("查询外部账户失败: %w", err)
    }
    return translateAccount(dto)
}

// translator 的单元测试
func TestTranslateAccount_Success(t *testing.T) {
    dto := &coreBankingAccountDTO{
        AccountNo:    "00123456789012",
        CustomerCode: "C0001",
        BalanceAmt:   1234500,
        BalanceCcy:   "156",
        StatusCode:   "01",
    }

    account, err := translateAccount(dto)
    assert.NoError(t, err)
    assert.Equal(t, AccountID("00123456789012"), account.ID)
    assert.Equal(t, AccountStatusActive, account.Status)
    assert.Equal(t, "12345.00", account.Balance.Amount().String())
    assert.Equal(t, "CNY", account.Balance.Currency())
}

func TestTranslateAccount_UnknownStatus(t *testing.T) {
    dto := &coreBankingAccountDTO{
        StatusCode: "99",
        BalanceCcy: "156",
    }

    _, err := translateAccount(dto)
    assert.Error(t, err)
    assert.Contains(t, err.Error(), "未知的账户状态码")
}

// OHS 的 API 数据传输对象——独立于内部领域模型
public record AccountResponse(
    String accountId,
    String holderName,
    String balance,
    String currency,
    String status,
    String lastUpdated
) {}

// OHS 控制器
@RestController
@RequestMapping("/api/v1/accounts")
public class AccountApiV1Controller {
    private final AccountQueryService queryService;
    private final AccountApiTranslator translator;

    @GetMapping("/{accountId}")
    public ResponseEntity<AccountResponse> getAccount(
            @PathVariable String accountId) {
        Account account = queryService.findById(new AccountId(accountId));
        AccountResponse response = translator.toApiResponse(account);
        return ResponseEntity.ok(response);
    }
}

// OHS 的转换器：领域模型 → API 响应
public class AccountApiTranslator {
    public AccountResponse toApiResponse(Account account) {
        return new AccountResponse(
            account.id().value(),
            account.holder().name(),
            account.balance().amount().toPlainString(),
            account.balance().currency().getCurrencyCode(),
            account.status().name().toLowerCase(),
            account.lastUpdated().toString()
        );
    }
}

syntax = "proto3";
package account.api.v1;

option go_package = "github.com/example/account/api/v1";
option java_package = "com.example.account.api.v1";

// 发布语言：账户服务的公开数据格式
service AccountService {
    rpc GetAccount(GetAccountRequest) returns (AccountResponse);
    rpc ListAccounts(ListAccountsRequest) returns (ListAccountsResponse);
}

message GetAccountRequest {
    string account_id = 1;
}

message AccountResponse {
    string account_id = 1;
    string holder_name = 2;
    MoneyValue balance = 3;
    AccountStatus status = 4;
    google.protobuf.Timestamp last_updated = 5;
}

message MoneyValue {
    string amount = 1; // 使用字符串避免浮点精度问题
    string currency = 2; // ISO 4217 字母码
}

enum AccountStatus {
    ACCOUNT_STATUS_UNSPECIFIED = 0;
    ACCOUNT_STATUS_ACTIVE = 1;
    ACCOUNT_STATUS_FROZEN = 2;
    ACCOUNT_STATUS_CLOSED = 3;
}

// ERP Adapter：封装 JCo/RFC 调用
public class SapMaterialAdapter {
    private final JCoDestination destination;

    public BapiMaterialDto getMaterial(String materialNumber) {
        JCoFunction function = destination
            .getRepository()
            .getFunction("BAPI_MATERIAL_GET_DETAIL");

        function.getImportParameterList()
            .setValue("MATERIAL", materialNumber);

        function.execute(destination);

        JCoStructure header = function.getExportParameterList()
            .getStructure("MATERIAL_GENERAL_DATA");

        return new BapiMaterialDto(
            header.getString("MATERIAL"),
            header.getString("MATL_DESC"),
            header.getString("BASE_UOM"),
            header.getString("MATL_GROUP"),
            header.getString("MATL_TYPE")
        );
    }
}

// Translator：BAPI 结构 → 领域对象
public class MaterialTranslator {
    public Material toDomain(BapiMaterialDto bapi) {
        return Material.reconstitute(
            new MaterialId(bapi.materialNumber().trim()),
            bapi.description().trim(),
            mapUnitOfMeasure(bapi.baseUom()),
            mapMaterialGroup(bapi.materialGroup()),
            mapMaterialType(bapi.materialType())
        );
    }

    private UnitOfMeasure mapUnitOfMeasure(String sapUom) {
        return switch (sapUom.trim()) {
            case "EA" -> UnitOfMeasure.EACH;
            case "KG" -> UnitOfMeasure.KILOGRAM;
            case "M"  -> UnitOfMeasure.METER;
            case "L"  -> UnitOfMeasure.LITER;
            default -> throw new TranslationException(
                "未知的 SAP 计量单位: " + sapUom);
        };
    }
}

// Facade：领域语言接口 + 缓存
public class ExternalMaterialService {
    private final SapMaterialAdapter adapter;
    private final MaterialTranslator translator;
    private final Cache<String, Material> cache;

    public Material findMaterial(MaterialId id) {
        return cache.get(id.value(), key -> {
            BapiMaterialDto dto = adapter.getMaterial(key);
            return translator.toDomain(dto);
        });
    }
}