浅谈项目代码规范

代码规范，此话题略范。从何说起？各司企皆具规范，大同小异，也有自称一派者，稀也。

官方规范

《PHP PSR 标准规范》是现有的标准规范，本人也是该规范的追随者，求同存异，会加一些自己的习惯进去，此习惯主要来自于项目经验。

如果你还没有看过官方标准规范，建议你进去看下。

代码规范的优势

齐心协力 意思是认识一致，共同努力。出自《墨子·尚贤》。

此成语充分的说明了代码规范的优势。在阅读代码的时候，阅读者会因为代码中的注释，规范命名，加速了非己所写代码的理解。阅读效率上来了，带来了更好的开发效率，行话曰：代码是写给人看的。此处的人，是你也是你的团队成员。

推荐的代码规范

目前我自己形成了一套编写习惯，略觉可扬，此习惯也是今年（2021）初具形态，故以示之，望与众行内人士共论之。若有增进之处，望畅言，笑迎之。

子曰：三人行，必有我师焉。择其善者而从之，其不善者而改之。

代码规范思路举例

我将自己写的 demo 展示如下：

app/Http/Controllers/Api/AuthController.php

    // 会员-登录
    public function login(Request $request)
    {
        $rules = [
            'username' => 'required|alpha_num|between:3,20',
            'password' => 'required|alpha_num|between:6,12',
        ];
        $messages = [];
        // 替换 传参 为指定内容
        $customAttributes = [
            'username' => '用户名',
            'password' => '密码',
        ];
        $validator = Validator::make($request->all(), $rules, $messages, $customAttributes);
        if ($validator->fails())
        {
            return response()->json([
                'code'   => 403,
                'errors' => $validator->errors()->toArray()
            ], 403);
        }

        // users.username
        $username = $request->post('username');
        // users.password
        $password = $request->post('password');

        // 校验用户名是否存在
        if (User::where('username', $username)->exists() === false)
        {
            return response()->json([
                'code'   => 403,
                'errors' => ['username' => '会员不存在']
            ], 403);
        }
        $user = User::where('username', $username)->first();
        // 校验用户密码
        if (User::generatePassword($password, $user->salt) != $user->password)
        {
            return response()->json([
                'code'   => 403,
                'errors' => ['password' => '密码错误']
            ], 403);
        }

        $token  = UserToken::generateToken($user->id);
        $key    = UserToken::getTokenKey($token);
        // 60 * 60 * 24 * 30, 30 day
        $second = 2592000;

        DB::beginTransaction();
        try {
            // redis 写入 token
            Redis::setEx($key, $second, $token);
            // token 写入数据库
            UserToken::setToken($user->id, $token);

            DB::commit();
        } catch (\Exception $e) {
            DB::rollBack();

            $context = [
                'function'  => __CLASS__.'->'.__FUNCTION__.'()',
                'line'      => __LINE__,
                'error'     => $e->getMessage()
            ];
            Log::channel('api-controller')->error('用户登录', $context);

            return response()->json([
                'code'   => 403,
                'errors' => ['登录失败']
            ], 403);
        }

        $data = [
            'token'     => $token,
            'username'  => $username,
        ];

        return response()->json([
            'code'      => 200,
            'data'      => $data,
            'message'   => 'success'
        ], 200);
    }// login() end

以上代码摘取于 api 控制器中，处理业务为 用户-登录。
代码分为 四个片区：

1. 输入内容验证区
2. 业务逻辑区
3. 业务处理区
4. 业务处理返回区

每一个片区都有自己的工作内容，互相关联，但互不干扰。如此而来，我们在读代码的时候，就更加容易做区分了。

app/Models/User.php

    /**
     * 生成记录
     *
     * @param string $username          users.username
     * @param string $password          users.password
     * @param string $payment_password  users.payment_password
     * @param string $phone             users.phone
     * @return int
     */
    public static function generateLog(string $username, string $password, string $payment_password = '', string $phone = ''): int
    {
        $salt = self::generateSalt(6);
        if (strlen($payment_password) > 0)
            $payment_password = self::generatePassword($payment_password, $salt);

        $insert = [
            'username'          => $username,
            'password'          => self::generatePassword($password, $salt),
            'payment_password'  => $payment_password,
            'phone'             => $phone,
            'salt'              => $salt,
            'is_lock'           => 'n',
            'is_frozen'         => 'n',
            'created_at'        => date('Y-m-d H:i:s'),
            'updated_at'        => date('Y-m-d H:i:s'),
        ];
        return self::insertGetId($insert);
    }// generateLog() end

模型方法，按照规范，应该是单一功能，如果是多功能，建议做拆分，提升维护性。

结语

寥寥数字，无法完全表明全意。总算是有个开始，将自己的经验总结吐出出来。望多包涵。

本作品采用《CC 协议》，转载必须注明作者和本文链接