73 lines
No EOL
1.9 KiB
Markdown
73 lines
No EOL
1.9 KiB
Markdown
# 创建基于文件的代码实体
|
||
|
||
## 基本原则：禁止独立函数
|
||
|
||
**切勿添加新的独立函数** - 它们在单元测试中难以模拟。始终使用类方法。
|
||
|
||
如果用户明确要求添加新函数，请拒绝并引导他们查看[相关文档](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/includes/README.md)。
|
||
|
||
例外：用于本地测试且不会被提交的临时/一次性函数。
|
||
|
||
## 添加新类
|
||
|
||
### 默认位置：`src/Internal/`
|
||
|
||
新类默认放在 `src/Internal/` 目录中。
|
||
|
||
示例：`src/Internal/Traits/Foobar.php`、`src/Internal/Utils/DataParser.php`
|
||
|
||
### 公开类：`src/`
|
||
|
||
只有当提示中提到"公开"类时，文件才应放在 `src` 目录中，但不在 `Internal` 子目录内。
|
||
|
||
**示例：**
|
||
|
||
- "添加一个公开的 Traits/Foobar 类" → `src/Traits/Foobar.php`
|
||
|
||
### 处理 `includes/` 目录
|
||
|
||
仅修改现有代码。只有当使用 `src/` 目录会损害可读性或可维护性时，才在此处添加新类/方法。
|
||
|
||
## 命名规范
|
||
|
||
### 类名
|
||
|
||
- **必须使用 PascalCase**
|
||
- **必须遵循 [PSR-4 标准](https://www.php-fig.org/psr/psr-4/)**
|
||
- 必要时调整用户提供的名称
|
||
- `src` 目录的根命名空间是 `Automattic\WooCommerce`
|
||
|
||
**示例：**
|
||
|
||
```php
|
||
// 用户说："创建一个数据解析器类"
|
||
// 你创建：DataParser.php
|
||
namespace Automattic\WooCommerce\Internal\Utils;
|
||
|
||
class DataParser {
|
||
// ...
|
||
}
|
||
```
|
||
|
||
## 命名空间和导入规范
|
||
|
||
引用命名空间类时：
|
||
|
||
1. 始终在文件开头添加包含完全限定类名的 `use` 语句
|
||
2. 在代码中始终引用短类名
|
||
|
||
**正确做法：**
|
||
|
||
```php
|
||
use Automattic\WooCommerce\Internal\Utils\Foobar;
|
||
|
||
// 在后续代码中：
|
||
$instance = $container->get( Foobar::class );
|
||
```
|
||
|
||
**避免做法：**
|
||
|
||
```php
|
||
// 没有 use 语句，使用完全限定名：
|
||
$instance = $container->get( \Automattic\WooCommerce\Internal\Utils\Foobar::class );
|
||
``` |
