datahub/docs/后端命名与编码规范.md

# 命名与编码规范

## 基本要求

1. 代码的执行性能为第一考量，其次是可读性，能批量处理的地方尽可能的批量处理，尤其是查询
2. 除特殊业务外，函数的方法和参数应尽可能的提供参数和返回类型的签名
3. 一个非关键业务执行失败，不应该影响后续业务的继续执行

## 基本原则

项目严格遵循 [PSR-1](https://www.php-fig.org/psr/psr-1/)、[PSR-4](https://www.php-fig.org/psr/psr-4/)、[PSR-12](https://www.php-fig.org/psr/psr-12/) 规范。

## 命名规范

| 类型 | 规范 | 示例 |
|------|------|------|
| 类名 | PascalCase | `OrderConsumer` |
| 方法名 | camelCase | `handleOrder()` |
| 类属性 | camelCase | `$eventDispatcher` |
| 类中数据库字段注解 | snake_case | `$platform_order_id` |
| 方法参数 | snake_case | `$order_id` |
| 方法内变量 | snake_case | `$total_amount` |
| 常量 | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |

## 示例

```php
class OrderService
{
    protected OrderRepository $orderRepository;  // 类属性: camelCase

    public function calculateTotal(array $order_items, float $discount_rate): float
    {
        $total_amount = 0;  // 方法内变量: snake_case

        foreach ($order_items as $item) {
            $item_price = $item['price'] * $item['quantity'];
            $total_amount += $item_price;
        }

        return $total_amount * (1 - $discount_rate);
    }
}
```

## 类型签名

方法必须声明参数类型和返回类型：

```php
public function findById(int $order_id): ?Order
```