如何在 jBilling 中创建 Customer 和 Product 自定义字段

2026-10-24AI 小顾

结论

不需要修改 jBilling 源代码。可以使用 jBilling 的 Meta Field（元字段或自定义字段）配置 Blood Group 和 Expiry Date：

将 Blood Group 关联到 Customer。部分版本还需要关联具体的 Account Type。
将 Expiry Date 关联到 Product/Item，并把数据类型设为日期。

字段创建后，jBilling 不会为每个字段单独生成 SOAP 方法，也不会在 WSDL 中增加新接口。客户端仍通过现有的 SOAP API，在对象的 metaFields 集合中读写字段值。

创建 Customer 自定义字段

使用有配置权限的管理员账号登录 jBilling 后台，找到类似下面的入口：

Configuration → Meta Fields

菜单名称因 jBilling 版本而异，可能显示为 Meta Fields、Customer Meta Fields，也可能位于 Account Types 配置中。

创建字段时可以使用以下设置：

Name: Blood Group
Entity Type: CUSTOMER
Data Type: STRING
Mandatory: 按业务需要设置

如果当前版本通过 Account Type 管理客户字段，需要进入客户所使用的 Account Type，在该类型下添加 Blood Group。否则，即使字段已经创建，也可能不会显示在 Add Customer 页面中。

血型一般可以使用字符串或枚举类型。如果当前版本支持列表选项，可以将可选值限制为：

A+
A-
B+
B-
AB+
AB-
O+
O-

这样可以减少输入格式不一致的问题。

创建 Product 自定义字段

在 Meta Fields 配置中添加另一个字段：

Name: Expiry Date
Entity Type: PRODUCT 或 ITEM
Data Type: DATE
Mandatory: 按业务需要设置

jBilling 的内部模型和 API 经常用 Item 表示界面中的 Product，因此有些版本会显示 ITEM，而不是 PRODUCT。

保存后，打开 Add Product 或产品编辑页面，确认字段是否已经显示。如果没有，需要逐项检查：

字段是否关联到正确的实体类型；
字段是否关联到当前产品类别；
当前用户角色是否有查看或编辑该字段的权限；
当前页面或主题是否包含 Meta Field 的渲染区域；
配置是否需要刷新缓存或重新登录才能生效。

通过 SOAP API 访问字段

系统不会生成以下形式的专用方法：

setBloodGroup(...)
setExpiryDate(...)

SOAP 接口通常不会发生变化。字段值通过通用的 MetaFieldValueWS 数组传递。例如，Java 客户端通常可以这样写：

MetaFieldValueWS bloodGroup = new MetaFieldValueWS(
    "Blood Group",
    null,
    DataType.STRING,
    false,
    "O+"
);

user.setMetaFields(new MetaFieldValueWS[] { bloodGroup });

产品的到期日期也使用相同的方式设置：

MetaFieldValueWS expiryDate = new MetaFieldValueWS(
    "Expiry Date",
    null,
    DataType.DATE,
    false,
    expiryDateValue
);

item.setMetaFields(new MetaFieldValueWS[] { expiryDate });

这里需要注意：

user 通常是 UserWS；
item 通常是 ItemDTOEx，也可能是当前版本使用的其他产品传输对象；
expiryDateValue 的具体 Java 类型和 SOAP 序列化格式取决于 jBilling 版本；
构造函数的参数也可能随版本变化。

如果当前客户端库没有提供上述构造函数，可以改用 setter：

MetaFieldValueWS value = new MetaFieldValueWS();
value.setFieldName("Blood Group");
value.setValue("O+");

user.setMetaFields(new MetaFieldValueWS[] { value });

读取字段时，可以遍历返回对象的 metaFields，按字段名查找：

for (MetaFieldValueWS field : user.getMetaFields()) {
    if ("Blood Group".equals(field.getFieldName())) {
        Object bloodGroup = field.getValue();
        // 使用 bloodGroup
    }
}

注意事项

Meta Field 的字段定义和字段值需要分开处理：

先在后台配置字段定义，包括字段名称、实体类型和数据类型。
再通过页面或 API，为具体的 Customer、Product 填写字段值。

SOAP WSDL 描述的是通用 Meta Field 数据结构，不会因为后台新建字段而增加接口，因此通常不需要重新生成客户端代理。如果 jBilling 升级后修改了 SOAP 数据结构，则需要使用与该版本对应的客户端库，或者重新生成 SOAP 客户端。

API 经常通过字段名称进行匹配。名称确定后应保持稳定，并确保大小写和空格完全一致。例如，始终使用 Blood Group，不要在不同调用中混用 Blood group 或 bloodGroup。