Python 函数库 APIs 编写指南_python import apis(1)
更多Python视频、源码、资料加群683380553免费获取
一致性
- 命名问题：你 API 中的命名是否和 Python 的习俗保持了一致性？ 我们命名应该与 PEP8 中所给出一致。PEP8 是 Python 官方的代码风格指南。为了保持命名与代码风格的一致性，建议使用 flake8 来规范你的 API 代码。
- 命名问题：API 中的命名是否一致？
- 术语的顺序： string_encode VS decode_string
- 缩写问题：activate_prev VS fetch_previous 以及 bin2hex VS strtolower
- 是否带有下划线： gettype VS get_class
- 单复数问题： values_list VS value_list
- 正负问题： button.enabled == True VS button.disabled == True - 空值问题：在空值意义的定义是否一致？目前的是最好的选择吗？
- 决定下面哪个代表了空值：None、 False、 []、 ‘’、 0
- 小心一些出人意料的值： bool(datetime.time(0)) == False 在Python3.5以前是这样 - 参数问题：在参数的顺序上是否具有一致性？例如：datetime.datetime(year, month, day, minute, second, microsecond) vs datetime.timedelta(days, seconds, microseconds, milliseconds, minutes, hours, weeks)
- 行为问题：在相似或者不同的行为上是否具有一致性？行为的不对称应该反应在格式的不对称上。例如，numbers.sort() VS sort(numbers)
灵活性
- 减小整体的不连续性
- 检查所有的类的功能是否单一职责？如果不是，就应该把那些类拆解开来。例如，一个从缓存中获取数据的类应该将其连接缓存服务器的步骤交给另一个类做。
- 检查函数的名称中是否包含了 and 或者是否包含多个操作。 如果确实如此，应该将这个函数拆成多个不同的函数。但是，如果这个函数经常被调用，那么可以保留一个结合了众多函数的函数。例如： print_formatted 函数可以被拆解为两个函数： print 和 formated
- 检查是否存在用户复制粘贴代码以改变函数功能的行为。 应该提供代码重构，回调功能。
- 检查在函数内部是否使用了属性值，如果有可以使用 get_something 方法代替。例如在 Djando 的 REST 框架中， CursorPagination 这个类仅仅支持一个固定大小的属性值：page_size，其原因就是这个类没有 get_page_size 这个方法。 这个问题再后来就通过上述方法解决了，即添加了 get_page_size 方法。
- 尽量避免隐藏可能有用的参数。例如我们的 API 中调用了另一个低级的 API 但是却没有展示这个低级 API 的参数情况
- 返回用户可能需要的一切信息
- 用户调用 API 时，要处理用户可能需要所有情况
- 在进行 API 测试的时候要测试每一个 mock.pathch。 虽然在程序运行的时候有一些东西不容易修改，但我们可以通过设置参数来修改某些东西。例如，Python 的内置函数 sched.scheduler 接受两个参数 timefunc 和 delayfunc。而我们没必要对 time.monotonic 和 time.sleep 两个函数进行 mock 测试，用户会根据自己的需求进行相应的改变。
- 建立抽象
- 按照底层实现的结构，去封装我们的函数成员与对象。例如 Beautiful Soup 就为多个分析器设计了同样的 API 结构。
- 提供多级的抽象结构，从最简单到最个性化。例如， Celery 既提供了 @app.task 这个装饰器，又提供了个性化的 task 类，而这个类继承于 celery.Task
- 提供摆脱封装的方法，让用户可以直接使用被抽象的资源和能力。例如，Django 的查询集合支持使用 .extra 方法将自定义的 SQL 与 ORM 进行结合来产生查询语句，同时也支持使用 .raw 来直接使用原生的 SQL 查询语句。
- 将底层实现中常见的错误进行封装，避免给用户直接报错。例如当 API 支持多个数据引擎的时候，出现数据库连接错误时，其显示信息应该一样。这个帮助用户找出问题所在，并且在修改数据库引擎时不会需要修改很多代码。
- 要有 Python 范
- 对于获取（get）和 设置（set）操作使用 Python 的自带属性
- 对于运算符重载要使用魔法方法（magic method）
- 对于简单的调试，使用 __repr__ 魔法方法
- 对于包含 打开-关闭 或者 开始-结束 这样的包含生命周期的问题，使用 with 语句
- 对于容易组合共同行为或者登记某些东西使用装饰器
- 对于迭代使用迭代器
- 对于复杂的逻辑问题使用生成器
- 对异步问题使用 asyncio
- 尽量使用内置的集合
- 对于简单的控制反演使用简单的高级函数，例如在 list.sort 函数中接受 key 参数作为等级高低计算函数以便计算列表的顺序。
- 对于复杂的流程问题，可以按照 函数/类的管道、继承、生成器的顺序逐一考虑。例如 管道问题可参考：python-social-auth 管道；继承问题可参考： Django 的类； 生成器问题可参考： Scrapy 的爬虫程序。
- 尊重鸭子式编程风格，要求谅解比谅解本身更加容易
- 国际化终端用户看到的字符串。
安全性
- 检查文档中的用于描述函数功能的警告性字眼，例如： warning，careful，remember to, dont’t forget。如果存在这些字眼，就得考虑如何更改代码使得函数更加安全稳定。
- 检查常见的错误，使用 Python 内置的 warning 模块来记录警告
- 明确不安全的行为。例如如果一些变量没有设置值，不要特意为它设置。不要到处写 fileds = None 这样的语句。
- 不要通过对象名称或者模块名称来隐式地链接代码，使用一个注册函数或者注册装饰器。例如 Django-admin 的注册问题不仅支持通过函数也支持装饰器。
- 不要依赖方法的调用顺序，尽量使用 with 语句。
- 快速报错： 程序出错就直接退出并不是 Python 式的思维
做了那么多年开发，自学了很多门编程语言，我很明白学习资源对于学一门新语言的重要性，这些年也收藏了不少的Python干货，对我来说这些东西确实已经用不到了，但对于准备自学Python的人来说，或许它就是一个宝藏，可以给你省去很多的时间和精力。
别在网上瞎学了，我最近也做了一些资源的更新，只要你是我的粉丝，这期福利你都可拿走。
我先来介绍一下这些东西怎么用，文末抱走。
（1）Python所有方向的学习路线（新版）
这是我花了几天的时间去把Python所有方向的技术点做的整理，形成各个领域的知识点汇总，它的用处就在于，你可以按照上面的知识点去找对应的学习资源，保证自己学得较为全面。
最近我才对这些路线做了一下新的更新，知识体系更全面了。
（2）Python学习视频
包含了Python入门、爬虫、数据分析和web开发的学习视频，总共100多个，虽然没有那么全面，但是对于入门来说是没问题的，学完这些之后，你可以按照我上面的学习路线去网上找其他的知识资源进行进阶。
（3）100多个练手项目
我们在看视频学习的时候，不能光动眼动脑不动手，比较科学的学习方法是在理解之后运用它们，这时候练手项目就很适合了，只是里面的项目比较多，水平也是参差不齐，大家可以挑自己能做的项目去练练。
（4）200多本电子书
这些年我也收藏了很多电子书，大概200多本，有时候带实体书不方便的话，我就会去打开电子书看看，书籍可不一定比视频教程差，尤其是权威的技术书籍。
基本上主流的和经典的都有，这里我就不放图了，版权问题，个人看看是没有问题的。
（5）Python知识点汇总
知识点汇总有点像学习路线，但与学习路线不同的点就在于，知识点汇总更为细致，里面包含了对具体知识点的简单说明，而我们的学习路线则更为抽象和简单，只是为了方便大家只是某个领域你应该学习哪些技术栈。
（6）其他资料
还有其他的一些东西，比如说我自己出的Python入门图文类教程，没有电脑的时候用手机也可以学习知识，学会了理论之后再去敲代码实践验证，还有Python中文版的库资料、MySQL和HTML标签大全等等，这些都是可以送给粉丝们的东西。
这些都不是什么非常值钱的东西，但对于没有资源或者资源不是很好的学习者来说确实很不错，你要是用得到的话都可以直接抱走，关注过我的人都知道，这些都是可以拿到的。
网上学习资料一大堆，但如果学到的知识不成体系，遇到问题时只是浅尝辄止，不再深入研究，那么很难做到真正的技术提升。
需要这份系统化学习资料的朋友，可以戳这里无偿获取
一个人可以走的很快，但一群人才能走的更远！不论你是正从事IT行业的老鸟或是对IT行业感兴趣的新人，都欢迎加入我们的的圈子（技术交流、学习资源、职场吐槽、大厂内推、面试辅导），让我们一起学习成长！