sap-hybris-commerce-best-practices（SAP Hybris 商务最佳实践）

SAP Hybris Commerce Best Practices

Comprehensive development guidelines and best practices for SAP Commerce Cloud (formerly Hybris). This skill covers the complete development lifecycle from data modeling to frontend and backoffice configuration.

Version Context

• SAP Commerce Cloud: 2211+ (September 2025 update)
• JDK: 21
• Spring Framework: 6.2
• Architecture: Service Layer (Jalo layer deprecated)

Quick Reference

Core Concepts

• Extension-based architecture: modular design with custom extensions
• Type System: metadata-driven data model defined in items.xml
• Service Layer: primary API for business logic (ModelService, FlexibleSearchService)
• ImpEx: CSV-based data import/export tool
• Spring Integration: DI, AOP, and bean management

Development Workflow

1. Define data model in *-items.xml
2. Run ant clean all to generate model classes
3. Perform system update to apply schema changes
4. Implement services with Spring DI
5. Create facades with DTOs for frontend
6. Build controllers for web/REST APIs
7. Create JSP views or use headless APIs
8. Configure Solr for search functionality
9. Write automated tests (unit + integration)

Topics

Backend Development

• Code Conventions - SAP Commerce coding style and formatting rules
• Java Development Guidelines - Coding standards, Spring patterns, service layer
• Create Extensions - Extension structure, types, and configuration
• Define Data Types - items.xml structure, types, relations
• Using ImpEx - Data import/export syntax and patterns
• Dynamic Attributes - Computed attributes without DB storage
• Services - Business logic implementation with Spring
• Properties Configuration - Externalize configuration
• Events - Event-driven architecture patterns
• Interceptors - Model lifecycle hooks
• Validation Framework - Declarative validation constraints
• Automated Testing - Unit and integration testing
• Code Quality - SOLID principles, extensibility, upgradability

Frontend Development

• Facades - Facade pattern, DTOs, converters
• Controllers - Spring MVC and REST controllers
• WCMS Components - CMS content management
• JSP Tags - Custom tag libraries
• JSP Views - View templates with JSTL

Search & Indexing

• Solr Integration - Search configuration, indexing, facets

Background Processing

• Tasks and CronJobs - Background task scheduling and execution

Backoffice

• Backoffice Configuration - cockpitng/backoffice config patterns (editor area, list view, search, wizards)

Common Patterns

Service + Facade Pattern

// Service (backend logic)
public interface ProductService {
	ProductModel findByCode(String code);
}

@Service
public class DefaultProductService implements ProductService {

	private final FlexibleSearchService flexibleSearchService;

	public DefaultProductService(final FlexibleSearchService flexibleSearchService) {
		this.flexibleSearchService = flexibleSearchService;
	}

	@Override
	public ProductModel findByCode(final String code) {
		// ...
		return null;
	}
}

// Facade (frontend API)
public interface ProductFacade {
	ProductData getProduct(String code);
}

@Service
public class DefaultProductFacade implements ProductFacade {

	private final ProductService productService;
	private final Converter<ProductModel, ProductData> converter;

	public DefaultProductFacade(final ProductService productService,
			final Converter<ProductModel, ProductData> converter) {
		this.productService = productService;
		this.converter = converter;
	}

	@Override
	public ProductData getProduct(final String code) {
		return converter.convert(productService.findByCode(code));
	}
}

Model Lifecycle

Create -> InitDefaults -> Prepare -> Validate -> Save
Load   -> LoadInterceptor
Delete -> RemoveInterceptor

Extension Dependencies

core -> facades -> storefront
     -> backoffice
     -> occ (REST API)

Best Practices Summary

DO

• Use Service Layer APIs (ModelService, FlexibleSearchService)
• Follow interface + implementation pattern
• Prefer constructor injection (Spring 6)
• Externalize configuration to properties files
• Write unit and integration tests
• Use facades with DTOs for frontend
• Validate input with interceptors or the validation framework
• Use ImpEx for data management
• Configure Solr for search functionality
• Follow SOLID principles

DON'T

• Use Jalo layer directly (deprecated)
• Use field injection (@Autowired on fields)
• Hardcode configuration values
• Expose models directly to frontend
• Modify generated model classes
• Skip system update after items.xml changes
• Perform heavy operations in interceptors
• Use embedded Solr in production

Quick Commands

# Build and generate models
ant clean all

# Run tests
ant alltests
ant unittests
ant integrationtests

# Solr management
ant startSolrServer
ant stopSolrServer

# Initialize/update system
ant initialize
ant updatesystem

Resources

• SAP Help Portal (requires authentication)
• SAP Community (forums and blogs)
• Local HAC: http://localhost:9001/hac

Note: this skill is based on SAP Commerce Cloud 2211+ (September 2025). For earlier versions, some features and APIs may differ.