企业官网建设流程全解析

接手这个项目时，我的第一反应是“这名字真不像个软件”。Madeira 听起来像是某款葡萄酒或者某个度假海岛，实际上它却是一个藏在供应链软件堆里的 EDI 解析转换组件。我司与合作方之间的采购订单一直靠人工搬运，每天上百封邮件，附带各种 .edi、.txt 的附件，里面的内容又长又怪，用普通工具根本没法直接读取。后来我把 Madeira 拉起来，用规则文件把那些又臭又长的 EDI 报文变成了结构清晰的 XML，再喂给内部订单系统，事情才算走上正轨。这篇东西就是这两三个月来的实战记录，目标读者是那些和我一样被迫去对接 EDI，又不打算重构整套系统的朋友。

如果你只是想找个现成的 SaaS 解决 EDI 传输，那不用看下去；但如果你手上有固定的 EDI 文档格式、需要自己做转换、并且希望在可控成本内把流程跑通，那 Madeira 值得你花二十分钟了解一下。

1. 为什么偏偏是它：Madeira 在 EDI 工具链里的位置

1.1 先说清楚 EDI 是什么，以及它为什么还活着

EDI（Electronic Data Interchange）本质上是企业之间传输结构化业务文档的一套老协议，从 60 年代末开始被运输业和零售业使用，现在全球供应链里依然大量存在。它最常见的样子是 X12（北美）和 EDIFACT（欧洲/国际），文档内容是纯文本，用特定的分隔符把段、元素、复合元素串起来。

举个例子，一条 X12 的采购订单片段长这样：

ST*850*0001~ BEG*00*SA*PO-1001**20250115~ REF*VR*SUPPLIER-88~ IT1*1*100*EA*12.50*UP*987654321012~ CTT*1~ SE*5*0001~

看不懂对吧？但它确实是订单：850 代表采购订单类型，BEG 里是订单号和日期，IT1 里是商品行、数量、单价和 UPC 码。这种格式没有任何 XML 或 JSON 的标记，全靠位置、段标识符和分隔符来表达含义。近几年的新系统都是 JSON API，而老牌零售商和物流商仍然在批量发 EDI 文件，于是“翻译”就成了一项刚需。

1.2 Madeira 和那些重型 EDI 平台的区别

市面上处理 EDI 的方案很多，大致分为两类：一类是 IBM Sterling、SAP PI 这种重型商业中间件，功能全但授权费能吓退中小团队；另一类是各种在线 EDI 交换服务，帮你把 EDI 转成 CSV 或 XML，可一旦遇到私有字段变体，你就得求着客服加 mapping，等他们排期。Madeira 属于另外一条路：它是一个本地运行的解析转换组件，本身不带网络传输，也不包办 B2B 网关，只负责把 EDI 文本吃进去，通过你定义的规则映射成目标格式吐出来。这样既避开了商业授权的成本，也保留了全字段的可控性。

我当初选中它，核心原因有三个：

• 本地解析，不需要把业务单据上传到第三方服务器，对采购数据来说更安心；
• 规则文件是文本化的 XML，改动流程可以用 Git 做版本管理，比在图形工具里点鼠标可追溯性强得多；
• 没有花哨的 UI，C++ 写了转换内核，解析速度很快，实用主义代表。

1.3 它能做的事情边界

要泼一盆冷水：Madeira 不是万能的。它不像 Sterling 那样自带 B2B 网关、加密传输、贸易伙伴管理。它解决的是 EDI 链条里“格式转换”这一段。以我目前的用法，它是这样嵌在整条链路里的：

接收 EDI 文件（FTP/SFTP/邮件附件） ↓ 前置简单清洗（去掉空行、合并拆分包，这步我也用 Madeira 的预处理钩子做） ↓ Madeira 按映射规则解析并生成 XML/JSON ↓ 写入内部队列 → ERP 订单模块消费

搞清楚这个边界很重要，否则你会像我第一次那样，以为装个它就能打通整个电子数据交换流程，结果还要自己去搞 SFTP 服务和消息队列。

2. EDI 的结构化陷阱：解析之前必须看懂的规则体系

2.1 分隔符是整套解析的命门

EDI 最磨人的地方在于分隔符不统一。X12 通常以*分隔元素，以~作为段终止符；EDIFACT 则用+和'。少数私有协议还会自定义分隔符。Madeira 的做法是把“分隔符配置”从代码里抽离出来，放进规则文件的头部，这样你不需要为了一个新伙伴改业务代码，只要增加一套配置。

我的规则文件开头通常长这样：

<edi-definition> <meta> <data-encoding>ASCII</data-encoding> <segment-terminator>~</segment-terminator> <element-delimiter>*</element-delimiter> <sub-element-delimiter>&gt;</sub-element-delimiter> </meta> ... </edi-definition>

注意>是转义后的>。EDI 文档里经常用>表示子元素分隔，所以 XML 文件里不能直接写，这个坑我第一次就踩了：漏了转义，结果解析器把整段<sub-element-delimiter>></sub-element-delimiter>当成非法标签，报了一堆看不懂的错误。

2.2 控制段是你最先要解析的东西

每个 EDI 文档都由控制段包起来。以 X12 为例，最外层是 ISA/IEA，中间层是 GS/GE，内层是 ST/SE。很多人第一次写映射会忽略 ISA 段，觉得那只是一堆定长字段的“信封”。但它里面藏了发送方 ID、接收方 ID、EDI 版本号、日期时间、控制编号，这些是做贸易伙伴追溯和审计的重要字段。

我在 Madeira 里总是先建一套“控制层映射”，把 ISA 里的每个位置都提取出来：

<segment code="ISA"> <field index="1" name="AuthorizationQualifier" /> <field index="2" name="AuthorizationInfo" /> <field index="3" name="SecurityQualifier" /> <field index="4" name="SecurityInfo" /> <field index="5" name="InterchangeSenderQualifier" /> <field index="6" name="InterchangeSenderId" /> ... </segment>

这里index从 1 开始，对应 ISA 段中按*分隔出来的元素位置。ISA 里还有个固定长度为 9 的 ISA12 版本号，比如005010，它决定了后续段的版本语义。不同版本下某些段可能少一个元素或多一个限定符，强烈建议在规则里把版本号校验打开，避免用 4010 的规则去解析 5010 的文档。

2.3 段重复、循环和嵌套：层次关系不能靠肉眼

EDI 和 XML 最大的差异在于：XML 天然有层级，EDI 是一维的段流。比如采购订单里，第一层的 BEG 后面跟着一组 IT1（商品行），每个 IT1 都可以有多个子段 PID（产品描述）、REF（参考号）、SCH（计划发货），这些子段在文本流里紧跟在 IT1 之后，直到出现下一个 IT1 才表示前一条商品行的子段结束。

Madeira 的规则文件里定义这种关系，用的方式类似一种“循环组”：

<loop name="ItemLoop" code="IT1"> <segment code="IT1" min="1" max="9999" /> <segment code="PID" min="0" max="1000" belongs-to="ItemLoop" /> <segment code="REF" min="0" max="1000" belongs-to="ItemLoop" /> <segment code="SCH" min="0" max="200" belongs-to="ItemLoop" /> </loop>

belongs-to是关键属性，它告诉解析器：当我在解析流中看到 PID 时，前面必须已经有一个 IT1 作为容器。如果你漏掉了这个从属关系，解析器会把所有 PID 都堆到第一个 IT1 下面，数据全乱。

2.4 限定符映射：把代码转成业务含义

EDI 里有一类字段叫限定符（Qualifier），比如 REF 段第二个元素可能是VR（供应商 ID）、PO（采购订单号）、ZZ（自定义）。单纯提取代码没有意义，业务系统要的是有含义的字段名。所以我的常规做法是用外部查表或者直接内联映射：

<segment code="REF"> <field index="1" name="ReferenceQualifier" /> <field index="2" name="ReferenceId" /> <lookup field="ReferenceQualifier"> <map from="VR" to="SupplierReference"/> <map from="PO" to="PurchaseOrderNumber"/> <map from="ZZ" to="CustomReference"/> </lookup> </segment>

这样生成的 XML 里，本来只有REF*VR*SUPPLIER-88，转换后就会变成<SupplierReference>SUPPLIER-88</SupplierReference>，内部下游系统看到这个标签一眼就懂，不再需要另写注释文档。

3. 从零到一：我跑通第一份 EDI 转 XML 的具体动作

3.1 环境准备，只有三步

首先是获取 Madeira 的可执行文件。我这个环境是 Ubuntu 20.04，直接解压官方 tar 包，里面包含madeira（命令行主程序）、lib动态库目录、schemas规则目录。启动前需要确认动态库路径：

export LD_LIBRARY_PATH=/opt/madeira/lib:$LD_LIBRARY_PATH chmod +x /opt/madeira/bin/madeira

其次是建立一个工作目录，我会把输入文件、规则文件、输出目录分开：

mkdir -p /data/edi/{in,out,rules,log}

最后准备一份最小的测试 EDI 文档，我给它的名字是sample_850.edi，就是文章开头那段示例，仅包含 ST、BEG、REF、IT1、CTT、SE，共 5 个段，足够验证基本路径。

3.2 根据报文手工“逆向”映射规则

这里有个经验：不要一开始就用复杂的规则文件。我习惯先写一个“抓全部字段”的规则，也就是把每个段的每个位置直接映射成SegmentCode_FieldIndex的通用字段名。这样做的好处有两个：一是快速验证解析器对整份文档的分段和分元素是否正确；二是用通用输出对比原文，能发现分隔符配置错误。

我的第一版规则是这样的：

<edi-definition> <meta> <data-encoding>ASCII</data-encoding> <segment-terminator>~</segment-terminator> <element-delimiter>*</element-delimiter> </meta> <parse> <segment code="ST"> <field index="1" name="ST_01" /> <field index="2" name="ST_02" /> </segment> <segment code="BEG"> <field index="1" name="BEG_01" /> <field index="2" name="BEG_02" /> <field index="3" name="BEG_03" /> </segment> <segment code="REF"> <field index="1" name="REF_01" /> <field index="2" name="REF_02" /> </segment> <segment code="IT1"> <field index="1" name="IT1_01" /> <field index="2" name="IT1_02" /> <field index="3" name="IT1_03" /> <field index="4" name="IT1_04" /> <field index="5" name="IT1_05" /> <field index="6" name="IT1_06" /> </segment> <segment code="CTT"> <field index="1" name="CTT_01" /> </segment> <segment code="SE"> <field index="1" name="SE_01" /> <field index="2" name="SE_02" /> </segment> </parse> <output type="xml"> <root name="PurchaseOrder"> <include segment="ST" /> <include segment="BEG" /> <include segment="REF" /> <include segment="IT1" /> <include segment="CTT" /> <include segment="SE" /> </root> </output> </edi-definition>

然后执行：

/opt/madeira/bin/madeira --input /data/edi/in/sample_850.edi \ --rules /data/edi/rules/step1_rules.xml \ --output /data/edi/out/sample_850.xml

这一步要观察两个结果：命令是否无报错退出，以及生成的 XML 里字段是否和原文元素一一对应。如果字段数量不对，回去查index是否从 1 开始。

3.3 把 AGNOSTIC 字段重命名为业务字段

确认通用映射正确后，第二步才是把字段重命名，并增加类型转换和限定符情况。我常用的做法是在output层里用别名和函数，而不是在parse层去改动。

<field name="OrderDate" source="BEG_05" type="date" format="yyyyMMdd" /> <field name="CustomerOrderNumber" source="BEG_03" /> <field name="SupplierReference" source="REF_02" when="REF_01=VR" /> <field name="LineItemQuantity" source="IT1_02" type="int" /> <field name="UnitPrice" source="IT1_04" type="decimal" />

这步完成后，输出 XML 会变成这样：

<PurchaseOrder> <OrderDate>2025-01-15</OrderDate> <CustomerOrderNumber>PO-1001</CustomerOrderNumber> <SupplierReference>SUPPLIER-88</SupplierReference> <LineItems> <LineItem> <LineNumber>1</LineNumber> <LineItemQuantity>100</LineItemQuantity> <UnitPrice>12.50</UnitPrice> <UPCCode>987654321012</UPCCode> </LineItem> </LineItems> </PurchaseOrder>

这个阶段最容易犯的错误是when条件写错，比如我把REF_01=VR写成了REF_01=='VR'，结果匹配不到任何值，供应商编号字段全部缺失。不同版本的规则语法之间确实存在差异，所以我建议你查一下你用的版本文档，但更重要的是：任何条件映射都要用最小样例做一次正反校验。

3.4 用批处理脚本建立可重复的转换流程

单个文件跑通不算完，你很快需要处理每天几十上百个文件。我直接写了个 Shell 脚本循环：

while read -r filename; do /opt/madeira/bin/madeira \ --input "/data/edi/in/${filename}" \ --rules "/data/edi/rules/purchase_order_rules.xml" \ --output "/data/edi/out/${filename%.edi}.xml" echo "${filename} processed, exit code: $?" >> /data/edi/log/run.log done < /data/edi/in/filelist.txt

后来我发现文件头行尾有 CRLF 或空行会导致解析报错，于是在进 Madeira 之前统一做一次预处理，把\r去掉：

sed -i 's/\r$//' "/data/edi/in/${filename}"

如果你也希望在规则内部做预处理，可以研究一下 Madeira 是否支持前置过滤器；如果不支持，在 Shell 层做清洗也不丢人。既然 C++ 原生解析性能足够，外部清洗几次的消耗可忽略不计。

4. 按小时计的排查：我踩过的四个真坑

4.1 连续分隔符和空元素的丢失问题

真实 EDI 报文里经常有空的元素，比如IT1*1*100*EA**12.50，中间那个空段表示包装未指定。我在第一版规则里没有处理空值，结果解析器直接跳过了这个元素，导致后面所有index错位：12.50 被放到了单价字段的前一个字段。这个问题比较隐蔽，因为大部分单测样例有值，直到对接真实文件才暴露。

后面我在规则文件里加了空元素保留策略：

<parse> <preserve-empty-fields>true</preserve-empty-fields> </parse>

同时把字段映射里可能为空的字段做成可空，避免 XML 输出里出现不完整的标签。这件事让我彻底明白了为什么业内反复强调“先用真实报文做解析、再用规则做映射”。

4.2 大文件导致的段丢失，不是内存问题，是缓冲截断

我遇到过一个 30MB 的 EDI 文件，解析到一半总是少段，而且每次少的位置还不一样。一开始我以为是系统内存不够，换了大内存机器照样复现。后来把文件拆成前后两半分别跑，发现后半段从某个位置开始突然没了。定位下来，是上游系统在生成这个文件时对段进行了语义层面的拆分，没有严格遵守段终止符规则——某个长字段值里包含~字符但没转义，导致我的解析器把它当成了段尾，提前切断了后面所有内容。

这种情况没法完全靠 Madeira 规避，必须在上游清洗阶段加一层脏字符过滤。我最后的处理方式是：在进入解析前，检查每个~后面的字符是否匹配已知段代码（ST、BEG、IT1等），如果不匹配，说明这个~是数据内嵌字符，转义成~再输出。虽说不优雅，但能保证解析流程不断。

4.3 字符集校验：ASCII 之外的意外字节

X12 规范默认要求 ASCII，但实际文件总会有各种意外，比如从 SAP 导出的 EDI 里带了 Unicode 的不可见字符、法语重音字符变成了问号。Madeira 在解析非 ASCII 字节的时候会直接报错或产生乱码。我的做法是在规则元数据里显式声明数据编码：

<data-encoding>UTF-8</data-encoding>

然后对上游文件做一次编码标准化：

iconv -f UTF-8 -t ASCII -c input.edi > clean.edi

这里-c会丢弃无法转换的字符。丢弃当然也不是最优解，但至少不会让整个流水线崩掉；如果业务上必须保留特殊字符，就需要和上游确认改用 EDIFACT 的 UNOC/UNOK 字符集标准，并调整分隔符策略。

4.4 控制段和业务段的循环拆分

另外一个很隐蔽的问题是：一个物理文件里有多个交易集。比如一个采购订单文件里，ISA 层包着两个 GS，每个 GS 里又有 ST/SE 和各自的 PO。如果规则只写了单交易集的处理，第二个 ST 以后的内容会被吞掉。

解决办法是把规则里的根节点设为 ISA，并定义 GS 和 ST 的循环：

<loop name="Interchange" code="ISA"> <segment code="ISA" /> <loop name="Group" code="GS"> <segment code="GS" /> <loop name="Transaction" code="ST"> <segment code="ST" /> ... <segment code="SE" /> </loop> <segment code="GE" /> </loop> <segment code="IEA" /> </loop>

这样输出 XML 里每一层都有对应包裹标签，下游拿到之后可以按控制编号拆分多条订单。做这个改造时，我特意用包含两个 GS 的样本来测，确认不会把第二个 ST 丢掉。

5. 转换之后的事：如何把输出接进现有系统

5.1 用根节点语义做自动路由

如果你的下游有多个系统，比如订单进 ERP、发货通知进 WMS、发票进财务，你可以在输出规则里为每种文档类型定义不同的根元素名。

拿的是 850 时输出根是PurchaseOrder，拿的是 856（发货通知/ASN）时输出根是ShipNotice。整体上，我让 Madeira 按传入的 mapping 文件来决定路由，Shell 脚本把 EDI 文件名里的单据类型作为参数传给转换命令，再按单据类型分发到不同的 Kafka topic。

case "${doctype}" in 850) topic="erp.purchase-order" ;; 856) topic="wms.ship-notice" ;; 810) topic="finance.invoice" ;; esac

这样转换和传输彻底解耦，Madeira 只负责“翻译”，消息中间件负责“传递”，业务方消费者只认 XML/JSON 结构，完全不需要了解 EDI 语法。

5.2 从 XML 到 JSON：对下游更友好

有些内部系统直接对接 JSON 更方便，Madeira 通常也支持 JSON 输出，取决于版本。如果没有 JSON 输出，我的方法是用xmlstarlet或jq在后处理里转。但更稳妥的方式是让 Madeira 先输出纯 XML，再通过标准的 XML-to-JSON 库转换，因为中间加一层 XML 可以保留字段顺序和重复组顺序。

5.3 失败重试与幂等消费

EDI 转 XML 是一次性操作，但消息中间件投递可能重复。所以我在下游消费者里实现了按 EDI 控制编号（ISA13）去重。这样即使同一个文件被重新转换并投递两次，也不会产生重复订单。这里我的经验是：必须在解析时就把 ISA13 提取出来，放到 XML 的顶层。因为后续所有业务表都可能需要关联到这个控制编号来做幂等键。

<field name="InterchangeControlNumber" source="ISA_13" />

这个字段是我在任何集成场景下都要求保留的第一个字段。

6. 如果你也要选型：Madeira 与常见替代品的取舍

6.1 一张表看明白定位

我用过 Web 工具、自研解析脚本、商业中间件和 Madeira，这里给出我个人的适用评估：

看在眼里的核心差别是：商业中间件带来的是一整套“贸易伙伴管理”和“传输协议支持”，如果你只需要把落盘文件换成结构数据，上它属于杀鸡用牛刀；在线工具虽然省事，但你无法把规则文件纳入 CI/CD 管理，而且敏感报文外传的心理门槛很高。

6.2 什么时候我建议你别用 Madeira

我要说句公道话：如果你完全不懂 EDI 段的结构、也不看任何规范，只想“上传文件，得到数据库表”，那 Madeira 对你来说太底层。它需要你具备一定的 EDI 报读能力，哪怕是临时抱佛脚打开 X12 标准文档对着看。另外如果你的映射规则非常复杂，比如需要调用外部数据库、做多文件关联、启用复杂计算，那它也不是那块料。这时候应该考虑像 Smooks 这类更偏 Java 生态的数据转换框架，或者干脆自己在业务系统里写个转换模块。

不过对于大多数中型制造、零售、物流企业的“与某个伙伴跑通 EDI”任务，Madeira 的轻量恰好是优势：部署一个容器、挂上规则文件、写几十行胶水脚本，就能把这滩事收拾干净。

我个人到现在还是维持一个习惯：每个合作方新建一套规则目录，里面只放两类文件，一个是通用解析模板，一个是合作方专属的限定符映射。这样碰上格式漂移，我能把问题快速定位到是哪一层的映射出了问题，而不是在一锅汤汁里捞针。上面写到的那些坑，绝大多数不是 Madeira 自身的问题，而是 EDI 格式的“脏”和“乱”被原原本本暴露出来了。一个能让你看见脏东西的解析工具，反而比一个把脏东西藏起来的黑盒更值得信任。如果你正准备开始整合类似数据，建议先拿一周的真实报文，把能想到的异常都列出来，再动手写规则文件——前期多花的时间，后面会十倍还给你。