woocommerce/.ai/skills/woocommerce-backend-dev/zh-cn/file-entities.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 标准
• 必要时调整用户提供的名称
• src 目录的根命名空间是 Automattic\WooCommerce

示例：

// 用户说："创建一个数据解析器类"
// 你创建：DataParser.php
namespace Automattic\WooCommerce\Internal\Utils;

class DataParser {
    // ...
}

命名空间和导入规范

引用命名空间类时：

1. 始终在文件开头添加包含完全限定类名的 use 语句
2. 在代码中始终引用短类名

正确做法：

use Automattic\WooCommerce\Internal\Utils\Foobar;

// 在后续代码中：
$instance = $container->get( Foobar::class );

避免做法：

// 没有 use 语句，使用完全限定名：
$instance = $container->get( \Automattic\WooCommerce\Internal\Utils\Foobar::class );