moov-io/ach-test-harness 镜像文档

概述

moov-io/ach-test-harness 是一个可配置的FTP/SFTP服务器和Go库，旨在交互式测试ACH（自动清算所）交易场景，能够模拟真实世界中的ACH发起、退回、变更、预注和转账流程。该工具提供灵活的响应规则配置，可根据交易详情（如账户号、金额、跟踪号等）自动执行返回、更正等操作，适用于ACH相关系统的开发和测试验证。

核心功能

• 可配置服务器：内置FTP/SFTP服务器，支持自定义根路径、端口、认证信息及被动端口范围
• 灵活响应规则：通过YAML配置文件定义匹配条件（账户号、金额范围、跟踪号等）和对应操作（返回、更正等）
• 管理接口：提供管理端口，支持指标监控（Prometheus格式）
• 场景模拟：支持模拟真实ACH交易场景，包括退回代码（如R03）、更正代码（如C01）等标准规则

使用场景

• ACH交易系统开发过程中的功能测试与集成测试
• 银行或***机构验证ACH处理流程的正确性
• 支付应用程序的兼容性测试，确保正确处理各类ACH返回和更正
• 培训环境中模拟不同ACH交易场景，验证操作人员应对能力

使用方法

Docker部署

拉取镜像

docker pull moov/ach-test-harness:latest

启动容器

默认配置下，服务器监听2222端口（FTP/SFTP），管理接口监听3333端口（指标）：

docker run -p 2222:2222 -p 3333:3333 moov/ach-test-harness:latest

配置说明

通过YAML配置文件自定义服务器参数和响应规则，配置文件结构如下：

ACHTestHarness:
  Servers:
    FTP:
      RootPath: "./data"          # 根目录路径
      Hostname: "0.0.0.0"         # 绑定主机名
      Port: 2222                  # FTP/SFTP端口
      Auth:
        Username: "admin"         # 认证用户名
        Password: "secret"        # 认证密码
      PassivePorts: "30000-30009" # 被动模式端口范围
      Paths:
        Files: "/outbound/"       # 文件上传路径
        Return: "/returned/"      # 返回文件路径
    Admin:
      Bind:
        Address: ":3333"          # 管理接口绑定地址（指标端口）
  Responses:                      # 响应规则配置
    - match:                      # 匹配条件（所有字段均需匹配）
        accountNumber: "***" # 匹配EntryDetail中的DFI账户号
        traceNumber: "121042880000001" # 匹配跟踪号
      action:                     # 匹配后执行的操作
        return:
          code: "R03"             # 返回代码（如R03表示账户不存在）

响应规则详细配置

match字段（所有非空字段需同时匹配）：

• accountNumber: 匹配EntryDetail中的DFI账户号（字符串）
• amount: 金额匹配条件
  • min: 最小金额（整数，分）
  • max: 最大金额（整数，分）
  • value: 固定金额（整数，分；与min/max二选一）
• debit: 空对象{}，表示仅匹配借方交易
• traceNumber: 跟踪号精确匹配（字符串）

action字段（支持的操作类型）：

• correction: ACH更正操作
  • code: 更正代码（如C01表示账户号更正）
  • data: 更正后的数据（如正确的账户号）
• return: ACH退回操作
  • code: 退回代码（如R01表示 insufficient funds）

示例配置

1. 按金额范围退回借方交易

- match:
    debit: {}  # 仅匹配借方交易
    amount:
      min: ***  # 最小金额：1000.00***（***分）
      max: ***  # 最大金额：1200.00***（***分）
  action:
    return:
      code: "R01"  # R01：资金不足

2. 按特定跟踪号退回

- match:
    # 匹配示例文件ppd-debit.ach中的跟踪号
    traceNumber: "121042880000001"
  action:
    return:
      code: "R03"  # R03：账户不存在

3. 更正账户号

- match:
    # 匹配示例文件utility-bill.ach中的账户号
    accountNumber: "744-5678-99"
  action:
    correction:
      code: "C01"        # C01：更正账户号
      data: "744567899"  # 更正后的账户号（去除分隔符）

项目状态

该项目目前处于开发阶段，可能会引入重大变更以达到稳定状态。欢迎社区反馈，建议试用代码或提供意见。

获取帮助

支持平台

• 64位 Linux（Ubuntu、Debian）
• macOS
• Windows

贡献指南

欢迎贡献！请查看 贡献指南 和 行为准则。项目使用 Go Modules，要求 Go 1.14 或更高版本。建议通过添加边缘案例、不同输入测试或贡献模糊测试来提高测试覆盖率。

许可证

Apache License 2.0，详见 LICENSE。