intershop-icm-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Intershop ICM Best Practices

Intershop ICM 最佳实践

Comprehensive best practices guide for Intershop Commerce Management (ICM) backend development, maintained by Intershop Engineering. Contains 68 rules across 20 categories, prioritized by impact to guide automated refactoring and code generation.

本指南是由Intershop工程团队维护的Intershop Commerce Management (ICM)后端开发综合最佳实践手册，涵盖20个类别共68条规则，按影响优先级排序，可指导自动化重构与代码生成。

When to Apply

适用场景

Reference these guidelines when:

Developing custom ICM cartridges
Creating or modifying REST API endpoints
Implementing B2B features (punchout, customer pricing, organizations, quotes, budgets)
Working with business objects and persistent objects
Writing pipelets and pipelines
Performing database initialization or migration
Implementing batch jobs and event handling
Customizing Solr search
Adding security measures
Writing tests
Deploying to Kubernetes environments

在以下场景中参考本指南：

开发自定义ICM cartridge
创建或修改REST API端点
实现B2B功能（punchout、客户定价、组织架构、报价、预算）
处理业务对象与持久化对象
编写pipelet与流水线
执行数据库初始化或迁移
实现批处理作业与事件处理
定制Solr搜索
添加安全防护措施
编写测试用例
部署至Kubernetes环境

Rule Categories by Priority

按优先级划分的规则类别


custom-
perf-
state-
b2b-
security-
rest-
cartridge-
test-
search-
i18n-
monitoring-
db-
pipeline-
guice-
job-
event-
impex-
logging-
template-
devops-

Priority	Category	Impact	Prefix
1	Customization Patterns	CRITICAL	`custom-`
2	Performance Optimization	CRITICAL	`perf-`
3	State Management & Data Flow	CRITICAL	`state-`
4	B2B Features	CRITICAL	`b2b-`
5	Security	CRITICAL	`security-`
6	REST API Development	HIGH	`rest-`
7	Cartridge Architecture	HIGH	`cartridge-`
8	Testing	HIGH	`test-`
9	Search	HIGH	`search-`
10	Internationalization	HIGH	`i18n-`
11	Monitoring & Observability	HIGH	`monitoring-`
12	Database & Persistence	MEDIUM-HIGH	`db-`
13	Pipeline & Pipelet Development	MEDIUM	`pipeline-`
14	Dependency Injection & Guice	MEDIUM	`guice-`
15	Job & Batch Processing	MEDIUM	`job-`
16	Events & Messaging	MEDIUM	`event-`
17	ImpEx Data Exchange	MEDIUM	`impex-`
18	Logging & Observability	MEDIUM	`logging-`
19	ISML Templates	MEDIUM	`template-`
20	Deployment & DevOps	LOW-MEDIUM	`devops-`


custom-
perf-
state-
b2b-
security-
rest-
cartridge-
test-
search-
i18n-
monitoring-
db-
pipeline-
guice-
job-
event-
impex-
logging-
template-
devops-

优先级	类别	影响程度	前缀
1	定制化模式	关键	`custom-`
2	性能优化	关键	`perf-`
3	状态管理与数据流	关键	`state-`
4	B2B功能	关键	`b2b-`
5	安全性	关键	`security-`
6	REST API开发	高	`rest-`
7	Cartridge架构	高	`cartridge-`
8	测试	高	`test-`
9	搜索	高	`search-`
10	国际化	高	`i18n-`
11	监控与可观测性	高	`monitoring-`
12	数据库与持久化	中高	`db-`
13	流水线与Pipelet开发	中	`pipeline-`
14	依赖注入与Guice	中	`guice-`
15	作业与批处理	中	`job-`
16	事件与消息传递	中	`event-`
17	ImpEx数据交换	中	`impex-`
18	日志与可观测性	中	`logging-`
19	ISML模板	中	`template-`
20	部署与DevOps	低中	`devops-`

Quick Reference

快速参考

1. Customization Patterns (CRITICAL)

1. 定制化模式（关键）

```
custom-no-direct-modification
```
- Never modify standard files directly
```
custom-use-extensions
```
- Use business object extensions for custom behavior
```
custom-cartridge-naming
```
- Follow layer-based cartridge naming conventions
```
custom-mark-changes
```
- Mark all customizations with comments
```
custom-microservices
```
- Prefer microservices for complex customizations

```
custom-no-direct-modification
```
- 切勿直接修改标准文件
```
custom-use-extensions
```
- 使用业务对象扩展实现自定义行为
```
custom-cartridge-naming
```
- 遵循基于分层的cartridge命名规范
```
custom-mark-changes
```
- 为所有定制化内容添加注释标记
```
custom-microservices
```
- 复杂定制化优先采用微服务架构

2. Performance Optimization (CRITICAL)

2. 性能优化（关键）

```
perf-caching-pattern
```
- Use caching for expensive operations
```
perf-query-optimization
```
- Optimize database queries, avoid N+1
```
perf-async-operations
```
- Use async processing for non-critical ops
```
perf-lazy-loading
```
- Use lazy loading with explicit fetch joins
```
perf-batch-processing
```
- Batch operations with flush/clear pattern
```
perf-connection-pooling
```
- Configure database connection pools properly
```
perf-memory-management
```
- Manage memory efficiently, stream large data
```
perf-session-size
```
- Minimize session size for scalability

```
perf-caching-pattern
```
- 对高开销操作使用缓存
```
perf-query-optimization
```
- 优化数据库查询，避免N+1问题
```
perf-async-operations
```
- 非关键操作使用异步处理
```
perf-lazy-loading
```
- 配合显式抓取连接使用延迟加载
```
perf-batch-processing
```
- 采用flush/clear模式实现批量操作
```
perf-connection-pooling
```
- 正确配置数据库连接池
```
perf-memory-management
```
- 高效管理内存，流式处理大数据
```
perf-session-size
```
- 最小化会话大小以提升可扩展性

3. State Management & Data Flow (CRITICAL)

3. 状态管理与数据流（关键）

```
state-repository-pattern
```
- Use repositories for BO lifecycle management
```
state-bo-po-separation
```
- Maintain strict BO/PO separation

```
state-repository-pattern
```
- 使用仓库模式管理业务对象生命周期
```
state-bo-po-separation
```
- 严格区分业务对象(BO)与持久化对象(PO)

4. B2B Features (CRITICAL)

4. B2B功能（关键）

```
b2b-punchout-implementation
```
- Implement punchout with proper security
```
b2b-customer-pricing
```
- Implement customer-specific pricing correctly
```
b2b-organization-hierarchy
```
- Manage organization hierarchies
```
b2b-approval-workflows
```
- Implement approval workflows with audit
```
b2b-budget-management
```
- Implement budget controls at multiple levels
```
b2b-quote-management
```
- Manage quotes with state machine and versioning
```
b2b-user-roles
```
- Implement flexible RBAC with delegation

```
b2b-punchout-implementation
```
- 实现具备适当安全防护的punchout功能
```
b2b-customer-pricing
```
- 正确实现客户专属定价
```
b2b-organization-hierarchy
```
- 管理组织层级架构
```
b2b-approval-workflows
```
- 实现带审计功能的审批工作流
```
b2b-budget-management
```
- 在多级别实现预算控制
```
b2b-quote-management
```
- 结合状态机与版本管理实现报价管理
```
b2b-user-roles
```
- 实现支持委托的灵活RBAC（基于角色的访问控制）

5. Security (CRITICAL)

5. 安全性（关键）

```
security-input-validation
```
- Validate all inputs with JSR-303
```
security-sql-injection
```
- Use parameterized queries
```
security-xss-prevention
```
- Use proper output encoding
```
security-sensitive-data
```
- Handle PII properly
```
security-access-control
```
- Implement RBAC correctly
```
security-csrf-protection
```
- Implement CSRF token validation

```
security-input-validation
```
- 使用JSR-303验证所有输入
```
security-sql-injection
```
- 使用参数化查询
```
security-xss-prevention
```
- 采用适当的输出编码防止XSS攻击
```
security-sensitive-data
```
- 妥善处理个人可识别信息(PII)
```
security-access-control
```
- 正确实现RBAC
```
security-csrf-protection
```
- 实现CSRF令牌验证

6. REST API Development (HIGH)

6. REST API开发（高）

```
rest-authentication
```
- Authenticate REST resources like server actions
```
rest-resource-objects
```
- Use proper resource object patterns
```
rest-handlers
```
- Use handlers for customizable REST resources
```
rest-pagination
```
- Implement proper pagination with metadata
```
rest-error-handling
```
- Use consistent error response format
```
rest-versioning
```
- Version APIs with URL path versioning
```
rest-hateoas
```
- Implement HATEOAS links properly

```
rest-authentication
```
- 像服务端操作一样对REST资源进行认证
```
rest-resource-objects
```
- 采用规范的资源对象模式
```
rest-handlers
```
- 使用处理器实现可定制的REST资源
```
rest-pagination
```
- 实现带元数据的规范分页
```
rest-error-handling
```
- 使用统一的错误响应格式
```
rest-versioning
```
- 通过URL路径实现API版本控制
```
rest-hateoas
```
- 正确实现HATEOAS链接

7. Cartridge Architecture (HIGH)

7. Cartridge架构（高）

```
cartridge-api-separation
```
- Separate API and implementation cartridges

```
cartridge-api-separation
```
- 分离API与实现类cartridge

8. Testing (HIGH)

8. 测试（高）

```
test-unit-test-services
```
- Unit test services with mocking
```
test-integration-pipelines
```
- Integration test pipelines
```
test-mock-repositories
```
- Mock repositories correctly
```
test-test-data-builders
```
- Use test data builders
```
test-rest-api-testing
```
- Test REST APIs comprehensively

```
test-unit-test-services
```
- 通过模拟对象对服务进行单元测试
```
test-integration-pipelines
```
- 对流水线进行集成测试
```
test-mock-repositories
```
- 正确模拟仓库对象
```
test-test-data-builders
```
- 使用测试数据构建器
```
test-rest-api-testing
```
- 全面测试REST API

9. Search (HIGH)

9. 搜索（高）

```
search-solr-customization
```
- Customize Solr search correctly
```
search-query-building
```
- Build search queries safely

```
search-solr-customization
```
- 正确定制Solr搜索
```
search-query-building
```
- 安全构建搜索查询

10. Database & Persistence (MEDIUM-HIGH)

10. 数据库与持久化（中高）

```
db-dbprepare-migration
```
- Use DBPrepare for initialization and migration
```
db-transaction-management
```
- Manage transactions properly
```
db-optimistic-locking
```
- Use optimistic locking for concurrency
```
db-po-lifecycle
```
- Manage PO lifecycle correctly

```
db-dbprepare-migration
```
- 使用DBPrepare进行初始化与迁移
```
db-transaction-management
```
- 正确管理事务
```
db-optimistic-locking
```
- 使用乐观锁处理并发
```
db-po-lifecycle
```
- 正确管理持久化对象(PO)的生命周期

11. Pipeline & Pipelet Development (MEDIUM)

11. 流水线与Pipelet开发（中）

```
pipeline-best-practices
```
- Follow pipeline design best practices
```
pipeline-error-handling
```
- Handle errors with transitions
```
pipeline-transactions
```
- Manage pipeline transactions correctly

```
pipeline-best-practices
```
- 遵循流水线设计最佳实践
```
pipeline-error-handling
```
- 通过分支处理错误
```
pipeline-transactions
```
- 正确管理流水线事务

12. Dependency Injection & Guice (MEDIUM)

12. 依赖注入与Guice（中）

```
guice-dependency-injection
```
- Use Guice dependency injection correctly

```
guice-dependency-injection
```
- 正确使用Guice依赖注入

13. Job & Batch Processing (MEDIUM)

13. 作业与批处理（中）

```
job-implementation
```
- Implement jobs with progress tracking
```
job-error-handling
```
- Handle job errors with retry and DLQ

```
job-implementation
```
- 实现带进度跟踪的作业
```
job-error-handling
```
- 通过重试与死信队列(DLQ)处理作业错误

14. Events & Messaging (MEDIUM)

14. 事件与消息传递（中）

```
event-publishing
```
- Publish domain events properly
```
event-consuming
```
- Consume events reliably with idempotency

```
event-publishing
```
- 正确发布领域事件
```
event-consuming
```
- 以幂等方式可靠消费事件

15. ImpEx Data Exchange (MEDIUM)

15. ImpEx数据交换（中）

```
impex-import-patterns
```
- Implement imports with streaming and validation
```
impex-export-patterns
```
- Implement exports with delta support

```
impex-import-patterns
```
- 实现支持流式处理与验证的导入
```
impex-export-patterns
```
- 实现支持增量导出的功能

16. Logging & Observability (MEDIUM)

16. 日志与可观测性（中）

```
logging-structured-logging
```
- Use structured logging
```
logging-correlation-ids
```
- Use correlation IDs
```
logging-log-levels
```
- Use appropriate log levels
```
logging-no-sensitive-data
```
- Never log sensitive data

```
logging-structured-logging
```
- 使用结构化日志
```
logging-correlation-ids
```
- 使用关联ID
```
logging-log-levels
```
- 使用合适的日志级别
```
logging-no-sensitive-data
```
- 切勿记录敏感数据

17. ISML Templates (MEDIUM)

17. ISML模板（中）

```
template-isml-best-practices
```
- Follow ISML coding standards
```
template-include-patterns
```
- Use includes properly
```
template-loop-optimization
```
- Optimize loops
```
template-caching
```
- Use fragment caching

```
template-isml-best-practices
```
- 遵循ISML编码标准
```
template-include-patterns
```
- 正确使用包含文件
```
template-loop-optimization
```
- 优化循环
```
template-caching
```
- 使用片段缓存

18. Deployment & DevOps (LOW-MEDIUM)

18. 部署与DevOps（低中）

```
devops-container-deployment
```
- Follow container deployment best practices

```
devops-container-deployment
```
- 遵循容器化部署最佳实践

19. Internationalization (HIGH)

19. 国际化（高）

```
i18n-localization
```
- Implement proper multi-language and multi-locale support

```
i18n-localization
```
- 实现完善的多语言与多区域支持

20. Monitoring & Observability (HIGH)

20. 监控与可观测性（高）

```
monitoring-apm-integration
```
- Integrate APM for performance and error tracking

```
monitoring-apm-integration
```
- 集成APM（应用性能监控）以跟踪性能与错误

Core Principles

核心原则

The Golden Rule: No Customization is Best

黄金法则：无定制化是最优选择

Before writing any custom code, always check:

Can this be achieved through back office configuration?
Is there an existing Intershop feature that meets this need?
Is this feature request standard-worthy (contact Intershop)?

在编写任何自定义代码前，务必先确认：

是否可通过后台配置实现该需求？
是否已有Intershop原生功能满足需求？
该功能是否具备标准化价值（可联系Intershop）？

Upgrade Safety

升级安全性

All customizations should be designed with upgrades in mind:

Use extension mechanisms over file modifications
Mark all changes with standardized comments
Keep custom cartridges separate from standard ones
Prefer microservices for complex integrations

所有定制化设计需考虑后续升级需求：

优先使用扩展机制而非修改文件
为所有变更添加标准化注释标记
将自定义cartridge与标准cartridge分离
复杂集成优先采用微服务架构

Layer Separation

分层隔离

Maintain clear boundaries between layers:

API (capi) - Public interfaces only
Internal - Implementation details
ORM - Database persistence
Pipeline - Business workflows

保持各层之间的清晰边界：

API (capi) - 仅包含公共接口
Internal - 实现细节
ORM - 数据库持久化
Pipeline - 业务工作流

How to Use

使用方法

Read individual rule files for detailed explanations and code examples:

rules/custom-use-extensions.md
rules/perf-caching-pattern.md
rules/b2b-punchout-implementation.md
rules/security-input-validation.md
rules/test-unit-test-services.md

Each rule file contains:

Brief explanation of why it matters
Incorrect code example with explanation
Correct code example with explanation
Additional context and references

阅读单个规则文件获取详细说明与代码示例：

rules/custom-use-extensions.md
rules/perf-caching-pattern.md
rules/b2b-punchout-implementation.md
rules/security-input-validation.md
rules/test-unit-test-services.md

每个规则文件包含：

规则重要性的简要说明
错误代码示例及问题解释
正确代码示例及说明
额外背景信息与参考资料

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded:

AGENTS.md

如需查看包含所有规则详细内容的完整指南，请参考：

AGENTS.md