magento-module-developer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Magento 2 Module Developer

Magento 2 模块开发者

Expert specialist in creating well-architected, maintainable, and extensible Magento 2 modules that seamlessly integrate with Magento's core framework following Adobe Commerce best practices.

专业专家，遵循Adobe Commerce最佳实践，创建架构优良、可维护且可扩展的Magento 2模块，可与Magento核心框架无缝集成。

When to Use

适用场景

Creating new Magento 2 modules or extensions
Implementing custom functionality
Building module architecture and structure
Setting up module dependencies and configuration
Implementing service contracts and APIs
Creating database schemas and data patches

创建新的Magento 2模块或扩展
实现自定义功能
构建模块架构与结构
配置模块依赖与设置
实现服务契约与API
创建数据库架构与数据补丁

Module Development Process

模块开发流程

1. Planning & Architecture

1. 规划与架构

Requirements Analysis: Break down functional and non-functional requirements
Architecture Design: Plan module structure and integration points
Database Design: Design entity relationships and data flow
API Design: Define service contracts and data transfer objects
Performance Considerations: Plan for scalability and optimization

需求分析：拆解功能性与非功能性需求
架构设计：规划模块结构与集成点
数据库设计：设计实体关系与数据流
API设计：定义服务契约与数据传输对象
性能考量：规划可扩展性与优化方案

2. Module Setup

2. 模块搭建

Module Structure: Create proper directory structure following Magento conventions:

app/code/Vendor/ModuleName/
├── etc/
│   ├── module.xml
│   ├── di.xml
│   ├── routes.xml
│   ├── system.xml
│   ├── acl.xml
│   └── db_schema.xml
├── Model/
├── Block/
├── Controller/
├── Api/
├── view/
└── registration.php

Registration: Create
```
registration.php
```
and
```
composer.json
```
Module Declaration: Create
```
etc/module.xml
```
with proper dependencies
Version Control: Set up Git with proper
```
.gitignore
```

模块结构：遵循Magento规范创建正确的目录结构：

app/code/Vendor/ModuleName/
├── etc/
│   ├── module.xml
│   ├── di.xml
│   ├── routes.xml
│   ├── system.xml
│   ├── acl.xml
│   └── db_schema.xml
├── Model/
├── Block/
├── Controller/
├── Api/
├── view/
└── registration.php

注册配置：创建
```
registration.php
```
与
```
composer.json
```
文件
模块声明：创建带有正确依赖的
```
etc/module.xml
```
版本控制：配置Git并设置合适的
```
.gitignore
```

3. Core Implementation

3. 核心实现

Models & Entities

模型与实体

Entity models extending
```
Magento\Framework\Model\AbstractModel
```

Resource models extending

Magento\Framework\Model\ResourceModel\Db\AbstractDb

Collections extending

Magento\Framework\Model\ResourceModel\Db\Collection\AbstractCollection

Use
```
db_schema.xml
```
for database schema definitions

继承
```
Magento\Framework\Model\AbstractModel
```
的实体模型

继承

Magento\Framework\Model\ResourceModel\Db\AbstractDb

的资源模型

继承

Magento\Framework\Model\ResourceModel\Db\Collection\AbstractCollection

的集合类

使用
```
db_schema.xml
```
定义数据库架构

Repositories

仓库层

Implement repository pattern for data access
Create repository interfaces in
```
Api/
```
directory
Implement repositories in
```
Model/
```
directory
Use service contracts for clean API interfaces

实现仓库模式用于数据访问
在
```
Api/
```
目录下创建仓库接口
在
```
Model/
```
目录下实现仓库类
使用服务契约构建清晰的API接口

Service Classes

服务类

Business logic in service classes
Use dependency injection for all dependencies
Implement service contracts for extensibility

业务逻辑封装在服务类中
所有依赖均使用依赖注入
实现服务契约以保证可扩展性

Controllers

控制器

Frontend controllers extending
```
Magento\Framework\App\Action\Action
```
Admin controllers extending
```
Magento\Backend\App\Action
```
API controllers implementing service contracts

前端控制器继承
```
Magento\Framework\App\Action\Action
```
后台控制器继承
```
Magento\Backend\App\Action
```
API控制器实现服务契约

4. Configuration Files

配置文件

module.xml

xml

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="Vendor_ModuleName" setup_version="1.0.0">
        <sequence>
            <module name="Magento_Store"/>
        </sequence>
    </module>
</config>

xml

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="Vendor_ModuleName" setup_version="1.0.0">
        <sequence>
            <module name="Magento_Store"/>
        </sequence>
    </module>
</config>

di.xml

Configure dependency injection
Define preferences, virtual types, plugins
Use proper scope (global, frontend, adminhtml, webapi_rest, webapi_soap)

配置依赖注入
定义偏好设置、虚拟类型、插件
使用正确的作用域（global、frontend、adminhtml、webapi_rest、webapi_soap）

db_schema.xml

Define database tables, columns, indexes
Use proper data types and constraints
Follow Magento naming conventions

定义数据库表、列、索引
使用正确的数据类型与约束
遵循Magento命名规范

Design Patterns & Principles

设计模式与原则

Service Contracts

服务契约

Create interfaces in
```
Api/
```
directory
Implement clean API interfaces
Use data transfer objects (DTOs) for data exchange
Maintain backward compatibility

在
```
Api/
```
目录下创建接口
实现清晰的API接口
使用数据传输对象（DTO）进行数据交换
保持向后兼容性

Repository Pattern

仓库模式

Separate data access from business logic
Use repositories for all data operations
Implement proper error handling
Support transactions where needed

将数据访问与业务逻辑分离
所有数据操作均通过仓库实现
实现完善的错误处理
必要时支持事务

Dependency Injection

依赖注入

Use constructor injection only
Avoid service locator pattern
Leverage Magento's DI container
Use type hints for all dependencies

仅使用构造函数注入
避免使用服务定位器模式
利用Magento的DI容器
所有依赖均使用类型提示

Plugin System

插件系统

Use plugins to extend functionality
Prefer before/after plugins over around plugins
Avoid around plugins unless necessary
Document plugin execution order

使用插件扩展功能
优先使用before/after插件而非around插件
除非必要，否则避免使用around插件
记录插件执行顺序

Event/Observer Pattern

事件/观察者模式

Dispatch events for extensibility
Implement observers for loose coupling
Use proper event naming conventions
Document event data structure

分发事件以支持扩展性
实现观察者以实现松耦合
使用正确的事件命名规范
记录事件数据结构

Module Components

模块组件

Backend Components

后台组件

Models: Entity models, resource models, collections
Repositories: Data access layer implementations
Services: Business logic and application services
Controllers: Admin controllers and API endpoints
Blocks: Admin interface building blocks
UI Components: Admin grids, forms, and components

模型：实体模型、资源模型、集合类
仓库：数据访问层实现
服务：业务逻辑与应用服务
控制器：后台控制器与API端点
块：后台界面构建块
UI组件：后台网格、表单及组件

Frontend Components

前端组件

Controllers: Frontend page controllers and actions
Blocks: View logic and data preparation
Templates: PHTML template files with proper escaping
Layout Files: XML layout configurations
JavaScript: Frontend interaction and AJAX functionality
CSS/LESS: Styling and responsive design

控制器：前端页面控制器与动作
块：视图逻辑与数据准备
模板：带有正确转义的PHTML模板文件
布局文件：XML布局配置
JavaScript：前端交互与AJAX功能
CSS/LESS：样式与响应式设计

Database Components

数据库组件

db_schema.xml: Database schema definitions
Data Patches: Data migration and setup scripts
Schema Patches: Database structure modifications
Indexers: Custom search and filter indexers

db_schema.xml：数据库架构定义
数据补丁：数据迁移与设置脚本
架构补丁：数据库结构修改
索引器：自定义搜索与过滤索引器

Advanced Features

高级功能

API Development

API开发

Create REST endpoints with proper authentication
Implement GraphQL resolvers and schemas
Design clean API interfaces
Implement rate limiting and security measures

创建带有正确认证的REST端点
实现GraphQL解析器与架构
设计清晰的API接口
实现速率限制与安全措施

Event System Integration

事件系统集成

Dispatch custom events for extensibility
Implement event observers
Create before/after/around plugins
Use virtual types for flexibility

分发自定义事件以支持扩展性
实现事件观察者
创建before/after/around插件
使用虚拟类型提升灵活性

Caching & Performance

缓存与性能

Implement custom cache types and tags
Handle cache invalidation properly
Use lazy loading for expensive operations
Optimize database queries and joins

实现自定义缓存类型与标签
正确处理缓存失效
对耗时操作使用懒加载
优化数据库查询与连接

Multi-Store Support

多店铺支持

Handle multi-store configurations
Implement proper configuration scopes
Ensure proper data separation
Support store context switching

处理多店铺配置
实现正确的配置作用域
确保数据正确分离
支持店铺上下文切换

Best Practices

最佳实践

Code Quality

代码质量

Follow PSR-12 and Magento coding standards
Use
```
declare(strict_types=1);
```
in all PHP files
Implement comprehensive type hinting
Write unit and integration tests
Maintain high code coverage

遵循PSR-12与Magento编码规范
在所有PHP文件中使用
```
declare(strict_types=1);
```
实现全面的类型提示
编写单元测试与集成测试
保持高代码覆盖率

Security

安全

Implement input validation
Use proper output escaping in templates
Implement CSRF protection
Enforce proper access control (ACL)
Handle sensitive data appropriately

实现输入验证
在模板中使用正确的输出转义
实现CSRF防护
实施正确的访问控制（ACL）
妥善处理敏感数据

Performance

性能

Optimize database queries
Use proper indexes
Implement caching strategies
Monitor memory usage
Optimize collection loading

优化数据库查询
使用正确的索引
实现缓存策略
监控内存使用
优化集合加载

Extensibility

可扩展性

Provide extension points via plugins
Dispatch events for third-party integration
Allow configuration without code changes
Use interface segregation
Maintain backward compatibility

通过插件提供扩展点
分发事件以支持第三方集成
允许无需修改代码即可配置
使用接口隔离原则
保持向后兼容性

Testing

测试

Unit Tests: Test individual classes and methods
Integration Tests: Test module integration with core
Functional Tests: End-to-end test scenarios
Static Analysis: Use PHPStan/Psalm for code quality

单元测试：测试独立类与方法
集成测试：测试模块与核心的集成
功能测试：端到端测试场景
静态分析：使用PHPStan/Psalm进行代码质量检查

Documentation

文档

Technical documentation for developers
User documentation for end users
API documentation for all public APIs
Installation guides
Troubleshooting guides

面向开发者的技术文档
面向终端用户的用户文档
所有公开API的API文档
安装指南
故障排除指南

References

参考资料

Focus on creating modules that are maintainable, extensible, and aligned with Magento's enterprise-grade architecture principles.

专注于创建符合Magento企业级架构原则的可维护、可扩展模块。