Python 函数库 APIs 编写指南_python import apis(1)

最新推荐文章于 2024-09-22 00:14:22 发布

2401_84140776

最新推荐文章于 2024-09-22 00:14:22 发布

阅读量589

点赞数 15

分类专栏：程序员文章标签： python 开发语言

本文链接：https://blog.csdn.net/2401_84140776/article/details/138294398

版权

程序员专栏收录该内容

192 篇文章 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所有方向的技术点做的整理，形成各个领域的知识点汇总，它的用处就在于，你可以按照上面的知识点去找对应的学习资源，保证自己学得较为全面。

最近我才对这些路线做了一下新的更新，知识体系更全面了。

在这里插入图片描述