为什么命名很重要
名字是团队成员（包括将来的自己）理解系统的第一手资料。一个好名字不仅是标签，更是意图的说明：
降低认知负担：读代码不需要猜测含义或补全联想。
推动更好的设计：能把职责描述得清楚，通常也意味着设计足够干净。
降低重构阻力：结构一目了然，动手改动也更从容。
缩短新成员上手时间：新人可以直接“阅读”代码，而不是拆谜题。
在 PHP 里这一点尤为重要。语言给了我们动态数组、灵活对象和自动加载的自由，如果缺少稳健的命名来约束，这些自由就很容易演变成混乱。
基础原则
清晰胜于简短：多敲几个字符，能省下后面无数次的解释。
名字要包含意图：让人看名字就知道它是什么、存在的理由是什么。
局部保持一致：在同一项目里选一套约定，并且贯彻到底——即便外面的世界更推崇另一套。
尽量使用领域语言：代码里的命名最好能映射业务术语，也就是所谓的“通用语言”。
避免误导：不要把类型塞进名字（例如 $userArray），也不要使用团队里少有人懂的缩写。
PHP 基础：大小写和约定
类与接口：使用 PascalCase，例如 OrderRepository、LoggerInterface。
方法与变量：采用 camelCase，例如 calculateTotal()、$orderItems。
常量：保持 UPPER_SNAKE_CASE，例如 DEFAULT_TIMEOUT_SECONDS。
命名空间：遵循 Vendor\Package\Feature 结构，兼容 PSR-4 自动加载。
文件：一份文件对应一个类，文件名与类名保持一致（如 OrderRepository.php）。
这些规则源自 PSR-1 与 PSR-12。真正重要的不是背诵条文，而是在项目内部形成统一的执行标准。
变量：名词、单位与可信的布尔值
变量总是在描述某个对象、状态或集合。名称越贴近那个概念，后续阅读就越轻松。下面是几个值得坚持的做法：
用精确的名词
不好：
$items = $cart->get();
更合适：
$cartItems = $cart->items();
集合用复数，元素用单数
$users = $userRepository->findActive();
foreach ($users as $user) { /* ... */ }
布尔值要像英文一样读
用 is、has、can、should、allows、supports 开头。
$isActive = $user->isActive();
$hasStock = $inventory->hasStock($sku);
$canRefund = $order->canRefund();
避免双重否定和模糊的标志：
不好：
$notFound = !$found;
$flag = true;
更合适：
$isFound = $repository->exists($id);
$isDraft = $post->isDraft();
在名字里标注单位或币种
单位写清楚可以直接消灭一批因换算引发的缺陷。
$timeoutSeconds = 30;
$distanceMeters = 1250;
$amountCents = 1999; // 19.99 美元
别把类型偷偷塞进名字里
不好：
$userArray = getUser(); // 后来其实是个 DTO...
更好：
$user = $userService->currentUser();
避免“杂物箱”式命名
$data、$info、$tmp 这类名字很难传达任何含义。若命名困难，通常意味着抽象可以再分拆——不妨考虑值对象或 DTO。
函数与方法：动词、返回值与副作用
函数要么执行操作，要么回答问题。命名时先想清楚它是哪一类，再决定用什么动词。
查询 vs 命令（CQS 思想）
查询：只读、不产生副作用，适合使用 find、calculate、list 这类描述性的动词；操作足够轻量时，可以保留 get。
命令：会改变系统状态，通常不返回数据或只返回一个成功标记，宜使用 create、update、delete、send、publish 等动作动词。
// 查询
$price = $pricing->calculatePrice($cart);
// 命令
$notifier->sendInvoiceEmail($invoiceId);
把 get 留给廉价、同步的访问
get 通常隐含“即时”“安全”的意味。如果方法需要访问外部服务或执行复杂逻辑，请改用 fetch、load、retrieve 等更准确的动词。
$settings = $config->get('checkout'); // 廉价操作
$user = $userRepository->fetchByEmail($email); // I/O（数据库）
用 ensure 表示幂等的创建逻辑
$apiKey = $keys->ensureExistsFor($userId);
布尔返回值要读起来像问题
if ($featureGate->isEnabled('new-checkout')) { /* ... */ }
避免“万能动词”
不推荐：
processOrder($order); // 怎么处理？
更好：
reserveInventoryFor($order);
chargePaymentFor($order);
generateInvoiceFor($order);
类、接口与 Trait：描述职责，而非实现细节
接口
在公共库或共享模块里，习惯在接口名后追加 Interface 后缀：
interface PaymentGatewayInterface
{
public function capture(Money $amount, string $paymentMethodId): CaptureResult;
}
如果是项目内部使用，当前上下文已经清楚表达用途，也可以不加后缀，但要始终如一。
Trait
为 Trait 添加 Trait 后缀，可以避免与实体类混淆：
trait TimestampsTrait
{
// 添加 createdAt / updatedAt 行为
}
抽象类与基类
Abstract 前缀或 Base 后缀都有人采用，但更推荐直接用角色来命名：
abstract class ScheduledTask // 比 AbstractTask 更能说明职责
{
abstract public function run(): void;
}
常见且有意义的后缀
Repository、Factory、Service、Controller、Subscriber、Listener、Specification、Policy、Presenter、Transformer 等后缀都承载着通用的语义。
事件类型通常以 Event 结尾，异常则以 Exception 收尾：
final class OrderPlacedEvent { /* ... */ }
final class PaymentFailedException extends RuntimeException { /* ... */ }
命名空间和目录：让 PSR-4 替你打理结构
命名空间层级应与目录结构一一对应，这样逻辑分层更清楚，也能减少自动加载配置。
App\
Checkout\
Domain\
Order\
Cart\
Payment\
Application\
PlaceOrder\
RefundOrder\
Infrastructure\
Persistence\
Http\
这种布局让类名自带上下文：
App\Checkout\Domain\Order\OrderRepository
App\Checkout\Application\PlaceOrder\PlaceOrderHandler
App\Checkout\Infrastructure\Http\PaymentWebhookController
一看到类型，就能判断它归属哪一层、承担什么职责。
常量与枚举：写出语义，拒绝魔法值
常量
class Cache
{
public const DEFAULT_TTL_SECONDS = 300;
}
枚举承载状态（PHP 8.1+）
枚举把状态写成强类型，也让命名保持唯一解释。
enum OrderStatus: string
{
case Pending = 'pending';
case Paid = 'paid';
case Shipped = 'shipped';
case Cancelled = 'cancelled';
public function isFinal(): bool
{
return in_array($this, [self::Shipped, self::Cancelled], true);
}
}
把相关逻辑放在枚举内部，命名自然贴近领域语境。
数组、DTO 和值对象
数组调用方便却缺乏语义。尽量把匿名结构换成可查的名字。
用具名类型替代“形状数组”
不推荐：
function createUser(array $data) {
// 期望 ['email' => ..., 'first_name' => ..., 'currency' => ...]
}
更好：
final class CreateUserInput
{
public function __construct(
public string $email,
public string $firstName,
public string $currencyCode
) {}
}
function createUser(CreateUserInput $input) { /* ... */ }
值对象用于领域概念和单位
final class Money
{
public function __construct(
public int $amountCents,
public string $currency
) {}
}
final class EmailAddress
{
public function __construct(public string $value) {
// 在这里验证格式
}
}
值对象既提供了语义明确的名字（如 Money、EmailAddress），也能在构造时守住不变量。
事件和异常：用后缀传达语境
事件
领域事件通常用过去式（OrderPlacedEvent、PaymentCapturedEvent）。
应用或集成事件 倾向现在式或命令式（SendNewsletter、UserExportRequested）。
final class OrderPlacedEvent
{
public function __construct(public OrderId $orderId) {}
}
异常
统一以 Exception 收尾，并以违反的业务规则命名，而不是描述表象。
final class InsufficientInventoryException extends DomainException {}
final class PaymentAuthorizationFailedException extends RuntimeException {}
同时提供可操作的消息与上下文；排查时，PaymentAuthorizationFailedException 远比“payment failed”好用。
数据库和迁移：让 SQL 与 PHP 对齐
数据库世界偏好 snake_case，PHP 则习惯 camelCase。选准映射方案，并且始终如一。
表和列
表名：可以用单数或复数，但要统一（orders 或 order）。
列名：推荐 snake_case（created_at、user_id）。
布尔值：沿用 is_active、has_stock 这样的前缀最易读。
外键：保持 user_id、order_id 这类格式。
中间表
用表名的字母顺序：order_product（不是 product_order），除非你的框架有既定模式。
别把枚举编码成魔法整数
倾向于字符串枚举（status = 'paid'）或 FK 到查询表。在 PHP 端映射到 OrderStatus 枚举。
迁移名字
让意图明显：
2025_01_15_101500_add_is_active_to_users_table.php
2025_01_20_090000_rename_total_to_subtotal_in_orders_table.php
API 和 CLI 命令：命名你暴露的界面
REST 风格的 HTTP 端点
资源用名词：/orders、/orders/{id}、/orders/{id}/items
自定义动作才用动词：/orders/{id}/cancel
查询参数是筛选条件：/orders?status=paid&limit=50
JSON 字段
字段命名保持统一（snake_case 或 camelCase）。若内部用 camelCase、外部要 snake_case，请在集中位置做转换。
CLI 命令
语义要直接、面向任务：
php bin/console orders:rebuild-index
php bin/console users:import --from=legacy.csv
除非领域内已有约定，否则少用 process、handle 这类泛词。
测试：写成可读的文档
测试面向的读者仅次于生产代码。命名清晰的测试在失败时会直接告诉你发生了什么。
类与文件名
测试类要镜像被测对象（SUT）：OrderRepositoryTest、PlaceOrderHandlerTest。一对一是简单有效的默认规则。
方法名
任选以下风格之一，并保持一致：
BDD 风格
public function it_calculates_total_for_multiple_items(): void
Given/When/Then 风格（内联或注解）
public function calculates_total_when_cart_has_discount_voucher(): void
测试辅助与替身
命名突出其职责：
OrderFactory // 测试场景构造器
FakePaymentGateway, StubClock, SpyMailer, InMemoryOrderRepository
数据提供者
/** @dataProvider invalidEmailProvider */
public function it_rejects_invalid_emails(string $email): void { /* ... */ }
注释与 PHPDoc：名字不够时
名字承担 80% 的沟通。把注释留给另外的 20%：
说明为什么，而非重复“做什么”
公共 API、复杂不变量用 PHPDoc 记录前提与约束
避免重复签名已有的类型信息
推荐写法：
/**
* 按创建顺序应用促销折扣。
* 这保留了合作伙伴依赖的历史行为。
*/
public function applyDiscounts(Cart $cart): void { /* ... */ }
不推荐写法：
/** @param int $userId 用户的 ID */
public function findById(int $userId): User { /* ... */ } // 信息冗余
国际化与语言选择
代码默认用英文，即便产品对外是本地语言。
保留核心领域术语，哪怕它们并非英文（如印尼工资系统里的 BPJSNumber）。
面向用户的文案放进翻译库，别写进标识符。
Composer 包与项目命名
发布到 Packagist 的包名就是公共 API 的一部分：
Composer 包名用小写连字符：acme/payment-gateway
命名空间通常镜像它，采用 PascalCase：Acme\PaymentGateway
描述务实准确；像 utils、helpers 这种笼统名字会迅速过期。
安全地重构名字：技术债会发生
重命名是健康行为。几条常用守则：
使用 IDE 的重构功能，确保引用全部同步。
公共接口分阶段弃用：保留旧名字，加上 @deprecated 并转发到新实现。
在 Changelog 中记录变更，告知使用方。
借助 Rector、PHP CS Fixer 等工具做机械式改名和风格统一。
凡是能提升团队理解的重命名，大多值得投入。
完整端到端示例（从请求到数据库）
下面用一个紧凑的结账流程，串起各层命名的协同方式。
领域
namespace App\Checkout\Domain;
final class OrderId
{
public function __construct(public string $value) {}
}
enum OrderStatus: string
{
case Pending = 'pending';
case Paid = 'paid';
case Shipped = 'shipped';
case Cancelled = 'cancelled';
public function isFinal(): bool
{
return in_array($this, [self::Shipped, self::Cancelled], true);
}
}
final class Money
{
public function __construct(
public int $amountCents,
public string $currency
) {}
}
Repository
namespace App\Checkout\Domain;
interface OrderRepository
{
public function nextId(): OrderId;
public function add(Order $order): void;
public function fetchById(OrderId $id): ?Order;
/** @return list<Order> */
public function listByStatus(OrderStatus $status, int $limit = 50): array;
}
注意动词：nextId、add、fetchById、listByStatus。没有通用的 save/get 汤。
应用服务
namespace App\Checkout\Application\PlaceOrder;
use App\Checkout\Domain\{OrderRepository, Money, OrderId};
final class PlaceOrderCommand
{
/** @param list<string> $productSkus */
public function __construct(
public string $customerEmail,
public array $productSkus,
public string $currency
) {}
}
final class PlaceOrderResult
{
public function __construct(public OrderId $orderId) {}
}
final class PlaceOrderHandler
{
public function __construct(
private OrderRepository $orders,
private PricingService $pricing,
private PaymentGatewayInterface $payments,
) {}
public function handle(PlaceOrderCommand $cmd): PlaceOrderResult
{
$orderId = $this->orders->nextId();
$total = $this->pricing->calculateTotal(
$cmd->productSkus,
$cmd->currency
);
$capture = $this->payments->capture(
new Money($total->amountCents, $total->currency),
paymentMethodId: $this->selectPaymentMethodFor($cmd->customerEmail)
);
if (!$capture->isSuccessful()) {
throw new PaymentAuthorizationFailedException($capture->reason);
}
// ...创建并持久化订单聚合（为简洁省略）
return new PlaceOrderResult($orderId);
}
private function selectPaymentMethodFor(string $email): string
{
// 领域特定逻辑
return 'card_default';
}
}
名字传达行为：PlaceOrderCommand（输入）、PlaceOrderResult（输出）、handle（应用边界）、calculateTotal、capture、isSuccessful。
HTTP 层
namespace App\Checkout\Infrastructure\Http;
final class PlaceOrderRequest // 把 JSON 映射到命令
{
/** @param list<string> $productSkus */
public function __construct(
public string $customerEmail,
public array $productSkus,
public string $currency
) {}
}
final class PlaceOrderController
{
public function __construct(private PlaceOrderHandler $handler) {}
public function __invoke(Request $request): Response
{
$payload = new PlaceOrderRequest(
customerEmail: $request->get('customer_email'),
productSkus: $request->get('product_skus'),
currency: $request->get('currency', 'USD'),
);
$result = $this->handler->handle(new PlaceOrderCommand(
$payload->customerEmail,
$payload->productSkus,
$payload->currency
));
return new JsonResponse(['order_id' => $result->orderId->value], 201);
}
}
看看名字如何在各层对齐："place order" 从 HTTP 流向应用再到领域，没有翻译的混乱。
数据库
orders
id CHAR(26) PRIMARY KEY
customer_email VARCHAR(255) NOT NULL
status ENUM('pending','paid','cancelled') NOT NULL
total_cents INT NOT NULL
currency CHAR(3) NOT NULL
created_at DATETIME NOT NULL
列名镜像领域术语；没有 misc_1，没有 flag。你未来在凌晨 2 点查看 blame 时的自己会感谢你。
命名的棘手角落：几个可借鉴的模式
区分相似操作
remove vs delete：
remove → 从集合中移除元素
delete → 从持久化层删除记录
create / register / enroll：选用领域里最自然的词。
update / patch / replace：若遵循 REST 语义，请明确区分。
澄清时间与时区
$expiresAtUtc, $createdAt // 若默认使用 UTC
如需本地时区，请在命名中体现，或使用 ZonedDateTime 这类封装。
可选 vs 必填
避免使用 maybe、opt 这类前缀；直接通过类型表达（?User、?string）。
若需要三态布尔，用枚举或状态值（比如 consentStatus）替代 ?bool。
临时变量
短暂的循环变量（$i、$line）可以接受，其余场景尽量给出有意义的命名。
“Manager / Helper” 气味
当你想写 SomethingManager 或 UtilHelper 时，考虑是否可以拆成更具体的小角色，如 TokenGenerator、Slugifier、ChecksumValidator。
代码审查清单
审查或重命名时，可以自问：
这个名字是否使用了业务团队熟悉的术语？
作用域清晰吗（类 vs 方法 vs 局部变量）？
布尔值读起来像问题吗？
集合名是复数且与元素名匹配吗？
函数名能看出是命令还是查询吗？
单位、货币、时区是否明示？
是否存在冗余的类型暗示或误导性的前缀？
不看实现能否猜出职责？
是否与周围命名约定保持一致？
如果这是公共 API，这个名字能否经得住时间考验？
借力工具（不是约束，而是护栏）
PHP CS Fixer / PHPCS：统一大小写、文件与类的布局。
PHPStan / Psalm：通过静态分析捕捉命名不一致、支持数组形状。
Rector：批量完成机械式重命名和弃用流程。
IDE 检查：如“未使用”“遮蔽”变量，往往提示命名或设计问题。
架构测试：例如用 PHPUnit 断言“Domain 层不得依赖 Infrastructure”，把命名纳入架构边界。
命名速查表
布尔：isX、hasX、canX、shouldX
查询：find、fetch、calculate、list、count
命令：create、update、delete、send、publish、reserve
集合：复数（$orders），元素单数（$order）
枚举：使用单数概念（OrderStatus::Paid）
事件：领域事件用过去式（OrderPlacedEvent）
异常：以 Exception 结尾，按违反的规则命名
单位：加单位后缀（$timeoutSeconds、$sizeBytes、$amountCents）
工厂：FooFactory::createFrom(...) 或 ::from(...)
Repository：add、fetchById、remove、listBy...
前后对比库（快速获胜）
命名模糊的变量
// 之前
$info = $service->get($id);
// 之后
$customerProfile = $profileService->fetchById($customerId);
泛化的函数
// 之前
function process($a, $b, $c) { /* ... */ }
// 之后
function generateInvoiceFor(Order $order, TaxRules $rules, Currency $currency): Invoice { /* ... */ }
把副作用藏在 “get” 里
// 之前
$report = $analytics->getMonthlyReport($month); // 会触发批处理
// 之后
$jobId = $analytics->scheduleMonthlyReport($month);
隐含单位
// 之前
sleep($timeout);
// 之后
sleep($timeoutSeconds);
save 的多重含义
// 之前
$orderRepository->save($order); // 插入？更新？还是 upsert？
// 之后
$orderRepository->add($order); // 写入新订单
$orderRepository->update($order); // 更新既有订单
与遗留代码和平相处
遇到遗留系统时，可考虑：
在边界层引入适配器名称，内部逐步使用新命名。
把第三方返回的原始数组包装成具名对象，靠近接口处完成转换。
循序渐进地重命名，从常见方法着手，避免“大手术”。
关键模块重命名前写批准测试（Golden Master）。
框架语境下的命名（Laravel、Symfony 等）
Laravel Eloquent：模型类默认单数（Order），表名复数（orders），顺势而为更省力。
Symfony：偏好显式服务和构造注入，按职责命名服务（Slugifier、OrderNumberGenerator）让容器一目了然。
事件/监听器：各框架略有差异，遵循框架约定可减少手工配置。
约定是一种“免费”的集成方式，善用它来降低仪式感。
常见命名陷阱
“Manager / Helper / Util” 大杂烩：通常意味着缺乏清晰抽象。
匈牙利命名法：2025 年不再需要 $strName；类型系统与 IDE 会帮你。
模糊缩写：若必须使用，请文档化并保持一致（SKU、VAT、OTP）。
过度前缀：在 OrderService 内无需 orderServiceProcessOrder()。
UI 驱动的命名：BlueButtonHandler 在换皮后立刻过时。
时间命名：newOrder、tempUser、finalData 很快就会说谎。
设立团队约定
命名确实包含品味，但团队共识可以降低摩擦：
撰写简明的命名 ADR（Architecture Decision Record）。
在仓库内提供示例（如 /docs/naming.md）。
在 PR 中鼓励提出具体替代方案（“建议用 PaymentCaptureResult，因为它描述的是捕获结果而非 HTTP 响应”）。
定期复盘（例如季度），随着经验更新约定。
