思考一次整体调整Python项目规范性的过程

本篇文章主要是记录整体调整Python数据统计分析项目规范性的过程,以及自己的一些思考。

为什么要调整?

  1. 主要是为了解决数据类程序不容易测试发现错误的现状。调整公共模块出错时抛出错误到业务层,便于报警模块上传错误信息到kafka,最后能主动发出报警邮件。以及方便加入报警之外的其他程序埋点。
  2. 调整所有Python数据统计分析程序满足pep8规范和Google Python风格规范,减少IDE提示。
  3. 完善代码注释和文档便于后续维护(之前的开发人员是Erlang风格,主张不写或者少写注释)。

认清程序当前现状

  1. 项目结构:目前整个数据统计分析项目的整体模式是各个以数据业务为导向的统计分析程序之间互相独立。各个数据统计分析程序几乎都依赖于底层的各个公共模块。包括数据库模块,日志模块,cdn相关模块、心跳模块、封装的阿里云各个产品的模块,封装的网宿云各个产品模块等等。
  2. 各个公共模块和各个统计分析程序前前后后经过熟人编写,风格完全不同,有C++风格,有Erlang风格,有Python,在IDE中出现各种不符合规范的提示。
  3. 对于公共模块中出现的错误,为了不影响业务层(原因是猜的),通常在本模块就直接捕获掉了,并没有抛出到业务层,也没有做过多处理,导致错误非常难以被发现。
  4. 有不少函数的返回值在处理成功和处理失败时,返回值的个数并不一致,导致低概率程序出现各种unpack错误。这类多返回值语言常见的bug错误全部需要调整。

确定程序调整原则

  1. 底层公共模块返回值需要保持个数一致。
  2. 和外界交互(数据库,oss,日志服务等等)的公共模块必须返回是否执行成功的状态,如果错误需要返回错误状态和错误原因到上一层。
  3. 公共模块封装的时候可以使用类,但是对外提供的功能接口优先使用函数形式。
  4. 所有的类统一调整成新式类。
  5. 删除公共模块中的无效代码。
  6. 完善注释。
  7. 完善文档。

记录程序调整过程

  1. qk_agent_praser改名为qk_agent_parser,需要在使用到此模块的地方进行一个调整。原因:拼写错误需要及时调整。qk_agent_praser对外函数接口没有调整,只有内部调整(减少split解析次数),对外无影响。
  2. check_up只改动少量格式(由于使用loop调度,程序退出后,存在sock绑定的addr没有释放的问题,导致下次单元测试时需要等待sock回收)。
  3. qk_email提供函数式对外接口,因此需要修改监控程序中使用到邮件的部分代码。
  4. qk_heartbeat增加两个函数式对外接口。修改心跳间隔为可配置,因此使用心跳模块需要调整调用方式。
  5. qk_ipdb调整类名和返回值,使用到ip数据库对应方法的地方都需要修改(ip查询以及数据统计程序)。
  6. 数据库连接池初始化返回值改动(返回连接池是否成功创建标志和创建失败的返回)。mysql_query的返回值有修改,查询失败时不是返回空列表而是返回False, str(e)。
  7. aliyun_oss:oss相关的返回格式,全部修改(对应的使用到oss的程序改动较大)。
  8. aliyun_cdn:返回值中返回请求状态码,请求text。
  9. aliyun_kafka:生产和消费都有返回值。
  10. aliyun其余各个模块返回值都有修改。
  11. 网宿查询带宽模块增加指定时间段查询,但时间不宜过长,否则会出现数据不完全(网速接口导致)。
  12. 根据公告模块修改对应的调用方法
  13. 调整所有的模块、类、方法、函数的注释,明确参数含义和返回值
  14. 补全文档

思考与感悟

或许以上的这些调整在现在看来是理所当然,是一开始写程序的时候就应该全部考虑到的,但是现实却由于各种原因,导致程序成为一个需要整体调整的鬼样子。

在调整的过程中,也会发现之前指定的一些调整原则存在某种程度的问题,导致最后弃用。比如其中的一个原则:

  • 业务层需要全部封装成类的形式,不能是纯函数,方便MixIn新增的额外功能,比如数据埋点接口、添加日志、属性检查等等任何你想MixIn的功能

乍一想来这个原则带来的好处很多,但是实际上带来的改动很大,这包括整个程序结构以及程序的表现形式和调用方法。最终还是弃用了这项原则。

最后,所有的开发人员都应该尽可能的参与需求分析,理解需求,明确自己要做的目的,牢记需求分析时女神李若彤的模样,而不是到验收交付时小笼包陈妍希的模样。

需求和验收的区别


参考:

Google-Python风格规范

捐赠:喜欢就请我喝一杯