【PHP系列直播】从代码细节聊一聊如何成为一名优秀的工程师 ...

梦里梦外; 2022-02-14 13:41 127阅读 0赞

# 直播回顾 #

[https://yq.aliyun.com/live/915][https_yq.aliyun.com_live_915]

# 主讲人 #

**周梦康（楚松）** [点击关注专家][Link 1]  
阿里云资深研发工程师，《深入 PHP 内核》作者之一

![\_\_meitu\_1][meitu_1]

# 内容提要 #

从代码细节聊一聊如何成为一名优秀的工程师

*  你的代码语意清晰吗？
 *  你的代码足够健壮吗？
 *  你的代码运行安全吗？
 *  你的代码考虑性能吗？

# 直播时间 #

2019年3月12日 19：30

# 直播地址 #

PHP技术进阶钉群：[https://c.tb.cn/F3.ZR58nS][https_c.tb.cn_F3.ZR58nS]

![php][]

**详情如下：**

![\_3\_meitu\_1][3_meitu_1]

# 更多内容 #

更多内容可关注PHP技术进阶云栖号（[https://yq.aliyun.com/teams/405][https_yq.aliyun.com_teams_405]）， 获取第一手技术资料

***[阿里开发者技术交流钉钉群的全向图【2019年】][2019]***

--------------------

> 好的语义表达是团队协作中高效迭代的润滑剂，好的语义表达是线上未知代码问题排查的指南针。

不要让其他人读不懂你的代码，其他人可能就是一周后的你。时刻以“如果你写的这段代码出现故障，一个陌生人接手你的代码需要多久能处理完这个bug”来监督自己。

日常中应该多多刻意提升自己语义表达，百利而无一害。那么我们应该从哪些细节去做好语义表达呢？

![image.png][]

> 以下代码全为我的艺术创作，不属于任何实际项目

## 命名 ##

### 案例1 ###

![image.png][image.png 1]

### 案例2 ###

function getUserInfo($teamId, $youId = [])
    {
    
    }

如果仅仅有这个函数名和参数名，谁能猜到参数的意义呢？  
![image.png][image.png 2]

### 案例3 ###

class Db
    {
        /**
         * @param string $table 数据库表名
         * @param array  $data  新增数据
         *
         * @return int 新增主键
         */
        public static function insert(string $table, array $data)
        {
            $id = mt_rand(1, 1000);
            return $id;
        }
    }
    
    class ViewLogStore
    {
        private $table = "view_log";
    
        function setHistory($data)
        {
            Db::insert($this->table, $data);
        }
    }

![image.png][image.png 3]

## 案例4 ##

假如业务代码里有这些类

class WechatUserModel{
    
    }
    
    class WechatGroupModel{
    
    }
    
    class WechatMessageModel{
    
    }

而我们查询数据库发现  
![image.png][image.png 4]

这样我们根据业务代码就非常不方便找到对应的表，而且其他人接手我们项目的时候，也会摸不着头脑。或者说这可能是三个人三次迭代开发造成的，那么他们彼此都没有去参考前面人的命名规则。

**来自灵魂的拷问**

![image.png][image.png 5]

# 注释 #

说完命名，下面说下注释。注释里还有什么学问？Are you kidding me?  
一个数组对象成员，你知道怎么写吗？  
类的魔术方法调用的注释，你知道怎么写吗？

### 对象数组 ###

/**
     * @var Ads[]
     */
    public $adsList = [];

![image.png][image.png 6]

$blocks = [];/** @var $blocks Block[] **/

![image.png][image.png 7]

### @method 的使用 ###

/**
     * @link http://manual.phpdoc.org/HTMLframesConverter/default/
     *
     * @method static int search(string $query, $limit = 10, $offset = 0)
     */
    class SearchServiceProxy
    {
        public static function __callStatic($method, $arguments)
        {
            if (!method_exists("SearchService", $method)) {
                throw new \LogicException(__CLASS__ . "::" . $method . " not found");
            }
    
            try {
                $data = call_user_func_array(["SearchService", $method], $arguments);
            } catch (\Exception $e) {
                error_log($e->getMessage());
                return false;
            }
    
            return $data;
        }
    }

![image.png][image.png 8]

### @deprecated 使用 ###

class SearchService
    {
    
        /**
         * @param string $query
         * @param int    $limit
         * @param int    $offset
         *
         * @return array
         * @deprecated
         */
        public static function search(string $query, $limit = 10, $offset = 0)
        {
            return [
                ["id" => 1, "aaa"],
                ["id" => 2, "bbb"],
            ];
        }
    }

![image.png][image.png 9]

### 注释其他注意事项 ###

注释解释张冠李戴，方法名更新，方法的功能业务注释没更新；复制别人的代码把 @author 信息也复制过来了，错误了还要把锅甩给别人。

> 注释更多参考 [http://manual.phpdoc.org/HTMLframesConverter/default/][http_manual.phpdoc.org_HTMLframesConverter_default]

## 函数、方法 ##

### 案例1 ###

先说明一句，不好的代码不妨碍它成为一个优秀的软件。PHP MySQL 烂代码多的去了。  
找到一个开源软件里面的代码，功能非常抢到，但是这个方法内容太多，一些不足点我标注出来了。  
![image.png][image.png 10]

### 案例2 ###

拿上面我举例子，还记得下面这种图吗？  
![image.png][image.png 3]

优化方案1

class ArrayUtils{
        public static function fetch($arr, $keys, $setNull = false)
        {
            $ret = array();
            foreach($keys as $key)
            {
                if ($setNull)
                {
                    $ret[$key] = $arr[$key];
                }
                else
                {
                    isset($arr[$key]) && $ret[$key] = $arr[$key];
                }
            }
            return $ret;
        }
    }
    
    
    class ViewLogStore
    {
        private $table = "view_log";
    
        function record($data)
        {
            $fields = array(
                'uid',
                'url',
                'referer',
                'created_time'
            );
            $data = ArrayUtils::fetch($data, $fields);
            Db::insert($this->table, $data);
        }
    }

优化方案2

class Db
    {
        /**
         * @param string $table 数据库表名
         * @param Entity $data  新增对象
         *
         * @return int 新增主键
         */
        public static function insert(string $table, Entity $data)
        {
            $array = $data->toArray();
            var_export($array); // test
    
            $id = mt_rand(1, 1000);
            return $id;
        }
    }
    
    class ArrayUtils
    {
        /**
         * 针对成员都是私有属性的对象
         *
         * @param      $obj
         * @param bool $removeNull 去掉空值
         * @param bool $camelCase
         *
         * @return array
         */
        public static function Obj2Array($obj, $removeNull = true, $camelCase = true)
        {
            $reflect = new \ReflectionClass($obj);
            $props = $reflect->getProperties(\ReflectionProperty::IS_PUBLIC | \ReflectionProperty::IS_PRIVATE | \ReflectionProperty::IS_PROTECTED);
    
            $array = [];
            foreach ($props as $prop) {
                $prop->setAccessible(true);
                $key = $prop->getName();
    
                // 如果不是驼峰命名方式，就把对象里面的 createTime 转成 create_time
                if (!$camelCase) {
                    $key = preg_replace_callback("/[A-Z]/", function ($matches) {
                        return "_" . strtolower($matches[0]);
                    }, $key);
                    $key = ltrim($key, "_");
                }
    
                $value = $prop->getValue($obj);
    
                if ($removeNull == true && $value === null) {
                    continue;
                }
    
                if (is_object($value)) {
                    $value = self::Obj2Array($value);
                }
    
                $array[$key] = $value;
            }
    
            return $array;
        }
    }
    
    class Entity
    {
        public function toArray(){
            return ArrayUtils::Obj2Array($this);
        }
    }
    
    class ViewLogEntity extends Entity
    {
        /**
         * @var int
         */
        private $uid;
    
        /**
         * @var string
         */
        private $url;
    
        /**
         * @var string
         */
        private $referer;
    
        /**
         * @var string
         */
        private $createdTime;
    
        /**
         * @param int $uid
         */
        public function setUid(int $uid)
        {
            $this->uid = $uid;
        }
    
        /**
         * @param string $url
         */
        public function setUrl(string $url)
        {
            $this->url = $url;
        }
    
        /**
         * @param string $referer
         */
        public function setReferer(string $referer)
        {
            $this->referer = $referer;
        }
    
        /**
         * @param string $createdTime
         */
        public function setCreatedTime(string $createdTime)
        {
            $this->createdTime = $createdTime;
        }
    }
    
    
    class ViewLogStore
    {
        private $table = "view_log";
    
        function record(ViewLogEntity $viewLogEntity)
        {
            Db::insert($this->table, $viewLogEntity);
        }
    }
    
    // 测试
    
    $viewLogEntity = new ViewLogEntity();
    $viewLogEntity->setUid(1);
    $viewLogEntity->setReferer("https://mengkang.net");
    $viewLogEntity->setUrl("https://segmentfault.com/l/1500000018225727");
    $viewLogEntity->setCreatedTime(date("Y-m-d H:i:s",time()));
    
    $viewLogStore = new ViewLogStore();
    $viewLogStore->record($viewLogEntity);

### 案例3 ###

这还是函数吗？（不仅仅是语义，属于错误）

/**
     * @method mixed fetchList(string $sql, array $argv);
     */
    class Model
    {
    
        public function __construct($table)
        {
    
        }
    }
    
    function getUserList($startId, $lastId, $limit = 100)
    {
        if ($lastId > 0) {
            $startId = $lastId;
        }
    
        $sql = "select * from `user` where id > ? order by id asc limit ?,?";
    
        $model = new Model('user');
        return $model->fetchList($sql, [intval($startId), intval($limit)]);
    }

`$startId`和`$lastId`两个参数重复

### 案例4 ###

尽量减少参数引用

function bad($input1, $input2, &$input3)
    {
        //...logic
    
        $input3 = "xxx";
    
        return true;
    }

### 案例5 ###

参数类型明确，返回值类型明确，不要出现 mixed。这个我直接拿官方的函数来举例，对权威也要有怀疑的眼光。纯属个人看法。  
![image.png][image.png 11]

### 案例6 ###

![image.png][image.png 12]

上面例子中你会发现这个`addUser`写得不想一个函数（方法）而像一个远程api接口。而且在右边的代码中需要每次使用的时候都要用`is_array`来判断。这是非常不友好的语义表达。PHP Java 这样的高级语言有异常，我们要善用异常。

![image.png][image.png 13]

好的语义表达是团队协作中高效迭代的润滑剂，好的语义表达是线上未知代码问题排查的指南针。这篇博客到这里就结束了，不知道你是否有一些收获呢？  
![image.png][]

[https_yq.aliyun.com_live_915]: https://yq.aliyun.com/live/915
[Link 1]: https://yq.aliyun.com/users/dy6hwsruw6kbe
[meitu_1]: /images/20220214/da1e24841f1c492db0f35b12910202c1.png
[https_c.tb.cn_F3.ZR58nS]: https://c.tb.cn/F3.ZR58nS
[php]: /images/20220214/6e38c144720d4f68be5cf838b5efe023.png
[3_meitu_1]: /images/20220214/73ce36cafee34523bcf760ab0df29f97.png
[https_yq.aliyun.com_teams_405]: https://yq.aliyun.com/teams/405
[2019]: https://yq.aliyun.com/articles/690084
[image.png]: /images/20220214/8acce64998304f2b8240b2be9a0af859.png
[image.png 1]: /images/20220214/5df7445180964f6091c03cf6e4bd3865.png
[image.png 2]: /images/20220214/c5d512208696407dbe8aef6ad9dd3a02.png
[image.png 3]: /images/20220214/57b3c81316a448c1b50aa36c1a974c58.png
[image.png 4]: /images/20220214/bd14b4930a5643cc8ac242d26443bebf.png
[image.png 5]: /images/20220214/76c6766dd1a74b439cb97caddad2f6bc.png
[image.png 6]: /images/20220214/89147035934b4840870162f0f76d6e9c.png
[image.png 7]: /images/20220214/bab63ee9fb1f4a03bf0d1a824e37733f.png
[image.png 8]: /images/20220214/c8504e62b8fa43a9a0c3aafbf966bce4.png
[image.png 9]: /images/20220214/18459927d4ff470283d3e379cd3223ea.png
[http_manual.phpdoc.org_HTMLframesConverter_default]: http://manual.phpdoc.org/HTMLframesConverter/default/
[image.png 10]: /images/20220214/b5dff7c421f6461ebda3273a0c4fb853.png
[image.png 11]: /images/20220214/f80dd8ae1317457f8be8e3285d2de04e.png
[image.png 12]: /images/20220214/b6086d9a13f34dabb69e64db83870b6a.png
[image.png 13]: /images/20220214/c49ebbea392042a28485d94b5c1ca606.png