关键概念
1. 一致的方法命名
// bad - inconsistent naming
class usermanager {
public function getuser($id) { /* ... */ }
public function fetchrole($id) { /* ... */ }
public function retrievepermissions($id) { /* ... */ }
}
// good - consistent naming pattern
class usermanager {
public function getuser($id) { /* ... */ }
public function getrole($id) { /* ... */ }
public function getpermissions($id) { /* ... */ }
}
命名方法时，一致性至关重要。在这个糟糕的例子中，我们使用三个不同的动词（get、fetch、retrieve）来执行类似的操作。这迫使开发人员记住同一类型操作的不同术语。好的示例在所有方法中一致地使用“get”，使 api 更可预测且更容易记住。当开发人员需要访问数据时，他们会直观地知道寻找以“get”开头的方法。
2. 预期回报类型
// bad - unexpected return types
class filehandler {
public function readfile($path) {
if (!file_exists($path)) {
return false; // unexpected boolean
}
return file_get_contents($path);
}
}
// good - consistent return types with exceptions
class filehandler {
public function readfile($path): string {
if (!file_exists($path)) {
throw new filenotfoundexception("file not found: {$path}");
}
return file_get_contents($path);
}
}
这个糟糕的例子混合了返回类型 - 有时返回字符串（文件内容），有时返回布尔值（false）。这给如何处理返回值带来了不确定性。这个很好的例子通过声明字符串返回类型并使用错误情况的异常来确保类型安全。这与 php 的内置行为相匹配，并使错误处理更加明确和可预测。
3. 可预测的参数顺序
// bad - inconsistent parameter order
class orderprocessor {
public function createorder($items, $userid, $date) { /* ... */ }
public function updateorder($date, $orderid, $items) { /* ... */ }
}
// good - consistent parameter order
class orderprocessor {
public function createorder($userid, $items, $date) { /* ... */ }
public function updateorder($orderid, $items, $date) { /* ... */ }
}
相似方法中的参数顺序应该保持一致。糟糕的示例将相似的参数放在不同的位置，使 api 变得混乱。好的示例保持了逻辑顺序：首先是标识符（userid/orderid），然后是主要数据（项目），最后是可选/元数据参数（日期）。这种模式符合 php 框架中的常见约定，并使 api 更加直观。
4. 清晰的方法行为
// bad - ambiguous behavior
class cart {
public function add($product) {
// sometimes creates new item, sometimes updates quantity
// unpredictable!
}
}
// good - clear, single responsibility
class cart {
public function addnewitem($product) { /* ... */ }
public function updatequantity($productid, $quantity) { /* ... */ }
}
方法应该有明确、单一的职责。坏例子的“add”方法不明确 - 它可能会添加一个新项目或更新一个现有项目。这个很好的例子将其分为两个不同的方法，具有明确的名称和目的。这使得代码的行为可预测，并遵循单一职责原则 (srp)。
5. 一致的错误处理
class PaymentProcessor {
public function processPayment(float $amount): PaymentResult {
try {
// Process payment
return new PaymentResult(true, 'Payment successful');
} catch (PaymentException $e) {
// Always handle errors the same way
throw new PaymentFailedException($e->getMessage());
}
}
}
此示例演示了通过异常进行一致的错误处理。当出现问题时，它总是抛出特定的异常类型（paymentfailedexception），而不是返回不同的类型或使用错误代码。这为整个应用程序的错误处理创建了一个可预测的模式。该方法还为成功案例使用专用的 paymentresult 对象，保持类型一致性。
这些实践中的每一种都有助于使代码更易于维护、更易于理解且不易出现错误，因为它的行为方式是开发人员基于 php 开发中的常见模式和约定所期望的方式。
