本教程旨在详细指导如何在Hybris注册页面中添加自定义属性，并确保其数据能够成功从前端传输至后端模型并持久化存储。文章将深入解析在Hybris数据流中集成新字段的关键步骤，包括扩展表单、数据传输对象、控制器和外观层，旨在解决常见的属性缺失验证错误及数据无法保存的问题，确保自定义字段的完整功能实现。
在hybris电商平台中，为注册页面添加新的自定义属性（例如，pan 潘卡号）是常见的业务需求。然而，在实现过程中，开发者常会遇到de.hybris.platform.servicelayer.exceptions.modelsavingexception: missing values for [pan]这样的模型保存异常，或者即使错误解决了，新添加的属性值也无法持久化到数据库中。这些问题通常源于数据从用户界面到后端模型的数据流不完整。本文将详细阐述如何通过扩展hybris的关键组件来解决这些问题。
1. 理解问题根源：数据流不完整
当您在items.xml中为CustomerModel添加一个新属性，并且该属性默认为强制（即未设置optional=”true”），如果在保存CustomerModel实例时未提供该属性的值，Hybris的MandatoryAttributesValidator就会抛出异常。即使您通过设置optional=”true”来绕过这个验证错误，如果前端输入的值没有被正确地捕获并传输到CustomerModel实例上，该值仍然无法被保存。因此，核心问题在于建立一个完整的数据传输链路。
2. 核心解决方案：扩展关键组件
要确保自定义属性值从注册表单正确地流向并保存到CustomerModel，您需要扩展并修改Hybris的以下核心组件：
- items.xml: 定义新属性的模型层。
- registerForm: 承载前端表单数据的Java Bean。
- RegisterData: 用于控制器与外观层之间数据传输的数据传输对象（DTO）。
- RegistrationPageController: 处理注册请求的控制器。
- CustomerFacade: 业务逻辑层，负责将RegisterData映射到CustomerModel并触发保存。
2.1 修改 items.xml 定义模型属性
首先，在您的扩展（extension）的items.xml文件中，为Customer类型添加新的属性。
<!-- Your extension's items.xml --> <items xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="items.xsd"> <itemtypes> <itemtype code="Customer" autocreate="false" generate="false"> <attributes> <!-- 添加新的Pan属性 --> <attribute qualifier="pan" type="java.lang.String"> <description>Pan Card number</description> <modifiers read="true" write="true" search="true" optional="false"/> <!-- 如果该字段在业务上是强制的，请保持 optional="false" 或不设置 (默认为 false)。 如果希望在前端未输入时允许保存，则设置为 optional="true"。 但为了解决“missing values”错误并确保数据保存， 关键在于确保值在保存前被设置到模型上。 --> </attribute> </attributes> </itemtype> </itemtypes> </items>
注意：修改items.xml后，务必运行ant all和updatesystem来更新数据库模式。
2.2 扩展 RegisterForm 添加表单字段
RegisterForm是spring mvc用来绑定前端表单提交数据的Java Bean。您需要创建一个新的类来扩展它，并添加您的自定义属性。
// myextension-web/src/com/mycompany/fulfilmentprocess/forms/MyRegisterForm.java package com.mycompany.fulfilmentprocess.forms; import de.hybris.platform.acceleratorstorefrontcommons.forms.RegisterForm; import javax.validation.constraints.Pattern; import javax.validation.constraints.Size; public class MyRegisterForm extends RegisterForm { private String pan; // 添加验证注解，例如正则表达式和长度限制 @Size(min = 10, max = 10, message = "{register.pan.invalid}") @Pattern(regexp = "[A-Z]{5}[0-9]{4}[A-Z]{1}", message = "{register.pan.invalid}") public String getPan() { return pan; } public void setPan(String pan) { this.pan = pan; } }
2.3 扩展 RegisterData 传输数据
RegisterData是控制器和外观层之间传递注册信息的数据传输对象。您也需要扩展它来包含新的pan属性。
// myextension-facades/src/com/mycompany/fulfilmentprocess/data/MyRegisterData.java package com.mycompany.fulfilmentprocess.data; import de.hybris.platform.commercefacades.user.data.RegisterData; public class MyRegisterData extends RegisterData { private String pan; public String getPan() { return pan; } public void setPan(String pan) { this.pan = pan; } }
2.4 扩展 RegistrationPageController 处理表单提交
RegistrationPageController负责处理注册页面的请求和表单提交。您需要覆盖其注册方法，以使用您的MyRegisterForm和MyRegisterData，并将pan值从表单传输到数据对象。
// myextension-web/src/com/mycompany/fulfilmentprocess/controllers/pages/MyRegistrationPageController.java package com.mycompany.fulfilmentprocess.controllers.pages; import de.hybris.platform.acceleratorstorefrontcommons.controllers.pages.Abstract='false'RegistrationPageController; import de.hybris.platform.acceleratorstorefrontcommons.forms.RegisterForm; // 导入原始RegisterForm import de.hybris.platform.commercefacades.user.data.RegisterData; // 导入原始RegisterData import de.hybris.platform.cms2.exceptions.CMSItemNotFoundException; import org.springframework.stereotype.Controller; import org.springframework.ui.Model; import org.springframework.validation.BindingResult; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestMethod; import javax.annotation.Resource; import com.mycompany.fulfilmentprocess.forms.MyRegisterForm; // 导入您的扩展表单 import com.mycompany.fulfilmentprocess.data.MyRegisterData; // 导入您的扩展数据 @Controller @RequestMapping(value = "/register") public class MyRegistrationPageController extends AbstractRegistrationPageController { @Override protected RegisterData create = new MyRegisterData(); protected MyRegisterData createRegisterData(final RegisterForm form) { final MyRegisterData registerData = new MyRegisterData(); // 调用父类方法，将公共字段从form复制到registerData super.populateRegisterData(form, registerData); // 将自定义字段从MyRegisterForm复制到MyRegisterData registerData.setPan(((MyRegisterForm) form).getPan()); return registerData; } // 覆盖注册方法以使用您的MyRegisterForm @RequestMapping(method = RequestMethod.POST) public String doRegister(final MyRegisterForm form, final BindingResult bindingResult, final Model model) throws CMSItemNotFoundException { // 调用父类的doRegister方法，确保所有标准注册逻辑被执行 // 注意：这里需要确保父类方法能接受MyRegisterForm或进行适当的类型转换 // 理想情况下，您会重写整个doRegister方法，但为了简洁，我们假设父类方法可以处理泛型RegisterForm // 并在内部调用createRegisterData return super.doRegister(form, bindingResult, model); } // 您可能还需要在getRegisterForm()方法中返回MyRegisterForm的实例 @Override protected RegisterForm getRegisterForm() { return new MyRegisterForm(); } }
注意：您需要更新Spring配置，将默认的RegistrationPageController替换为您的MyRegistrationPageController。
<!-- myextension-web/web/webroot/WEB-INF/config/spring-mvc-config.xml (或类似文件) --> <bean id="registrationPageController" class="com.mycompany.fulfilmentprocess.controllers.pages.MyRegistrationPageController" />
2.5 扩展 CustomerFacade 将数据映射到模型
CustomerFacade是业务逻辑层，它最终会调用服务层来创建或更新CustomerModel。您需要扩展它，以确保MyRegisterData中的pan值被正确地映射到CustomerModel实例。
// myextension-facades/src/com/mycompany/fulfilmentprocess/facades/customer/impl/MyDefaultCustomerFacade.java package com.mycompany.fulfilmentprocess.facades.customer.impl; import de.hybris.platform.commercefacades.user.impl.DefaultCustomerFacade; import de.hybris.platform.commercefacades.user.data.RegisterData; // 导入原始RegisterData import de.hybris.platform.core.model.user.CustomerModel; import com.mycompany.fulfilmentprocess.data.MyRegisterData; // 导入您的扩展数据 public class MyDefaultCustomerFacade extends DefaultCustomerFacade { @Override protected void populateModel(final RegisterData registerData, final CustomerModel customerModel) { // 调用父类方法，处理所有标准字段的映射 super.populateModel(registerData, customerModel); // 如果传入的是MyRegisterData，则将自定义字段映射到CustomerModel if (registerData instanceof MyRegisterData) { final MyRegisterData myRegisterData = (MyRegisterData) registerData; customerModel.setPan(myRegisterData.getPan()); } } // 您可能还需要重写registerCustomer方法，以确保它接收并处理MyRegisterData // 或者确保其内部调用的populateModel方法被正确地重写 @Override public void registerCustomer(final RegisterData registerData) { // 在这里，registerData将是MyRegisterData的实例 // populateModel方法会被调用，从而将pan值设置到customerModel super.registerCustomer(registerData); } }
注意：同样，您需要更新Spring配置，将默认的customerFacade替换为您的MyDefaultCustomerFacade。
<!-- myextension-facades/resources/myextension-facades-spring.xml (或类似文件) --> <bean id="customerFacade" class="com.mycompany.fulfilmentprocess.facades.customer.impl.MyDefaultCustomerFacade" parent="defaultCustomerFacade" />
3. 前端UI集成
在完成后端逻辑后，别忘了在您的jsp或html模板中添加新的输入字段。例如，在registrationPage.jsp（或类似文件）中：
<!-- ... 其他表单字段 ... --> <div class="form-group"> <label class="control-label" for="pan"><spring:theme code="register.pan" text="Pan Number"/></label> <div class="controls"> <form:input cssClass="form-control" id="pan" path="pan" type="text"/> <form:errors path="pan" cssClass="help-block"/> </div> </div> <!-- ... 其他表单字段 ... -->
并在您的资源包（例如messages_en.properties）中添加对应的标签和验证消息： register.pan=Pan Numberregister.pan.invalid=Please enter a valid 10-character PAN number (e.g., ABCDE1234F).
4. 总结与注意事项
通过上述步骤，您已经建立了一个完整的数据传输链，确保了自定义属性Pan能够从前端UI经过MyRegisterForm、MyRegisterData、MyRegistrationPageController最终传输到MyDefaultCustomerFacade，并被映射到CustomerModel中，最终持久化到数据库。
关键点回顾：
- 数据流完整性：确保每个层级都能够识别并传递新的属性值。
- 模型定义：items.xml中属性的optional修饰符决定了该属性在保存时是否必须有值。如果它在业务上是强制的，并且您希望在用户注册时就捕获它，那么确保值被正确传输到模型是解决MandatoryAttributesValidator错误的关键，而不是简单地将其设为optional=”true”。
- Spring Bean覆盖：确保您在Spring配置文件中正确地将默认的Hybris Bean替换为您的自定义实现（例如，通过parent属性或直接覆盖）。
- 缓存与系统更新：在修改items.xml后，务必执行ant all和updatesystem。对于Java代码的修改，需要重新部署您的扩展。
遵循这些步骤，您将能够成功地在Hybris注册流程中集成并持久化新的自定义属性。
