关于Django REST framework 的一些笔记

Django REST framework

以下为了撰写方便，直接把Django REST framework 简称为DRF。

整个DRF我觉得设计得满完整，甚至也有plugin的生态系，如果找不到合适的，也可以自己撰写DRF的plugin。刚开始上手的话有份官方的Tutorial可看：Quickstart - Django REST framework，建议把整份tutorial都念完会比较了解整个framework组件之间的关系，毕竟篇幅也不多，加上Quickstart也就8个页面而已。剩下的等实际编写嗲吗时遇到不太懂的时候，再去查询官网上详细一点的文件就行了，有时候真的文件说的不够清楚的话可能还是得去看一下代码。

这边记录一下几个我自己在阅读文件的时候花比较多时间理解的部份：

• 1 - Serialization - Django REST framework
  • 基本上就是在Django 的Model 上再多做一层包装，可以对API 做一些客制化设定，比如要显示哪些栏位、限定哪些权限...等等。
• Filtering - Django REST framework
  • 如果要针对不同的使用者得到不同的结果的话，就会需要用到filtering 的部份。
  • 可以针对使用者、网址、可使用参数做限制。
  • 有多种不同的filter 可以用，搜寻、排序、权限，也可以自己继承下来撰写客制化的filter。
• Routers - Django REST framework
  • 基本上跟Django 的dispatcher 写法差不多，但多了一些可以针对HTTP method 的设定ˇ等等。
• django-rest-framework/viewsets.py at master · encode/django-rest-framework · GitHub
  • 当时是因为对ViewSet可以使用的参数不太清楚，看文件又看不出个所以然，所以就跑去看代码了。

花了一点时间熟悉之后，我在后续使用上遇到最大的问题是在效率，因为我要去查询的资料总量满大的，所以查询常常都会等很久。还有DRF 预设的pagination 部份也没有处理得很好，查了一下发现也有很多人遇到，所以有满多文章在讲这件事的，这里列出我自己觉得比较有用的：

• Ditching Django REST Framework Serializers for Serpy · BetterWorks Engineering Blog
  • 这篇是作者因为DRF的Serializer实在是太慢，所以自己写了另外一个作serialization的library: serpy
• Optimizing slow Django REST Framework performance
  • 这篇是在讲怎么透过调整DRF 的Serializer 来处理query 时过慢的问题。
  • 要用上queryset.prefech_realted等等。
• Web API performance: profiling Django REST framework
  • Get your ORM lookups right.
  • Your database lookups will be the bottleneck.
  • Work on performance improvements selectively.
  • You don't always need to use serializers.
  • 自己写个框架：即便只有用到DRF的APIView其他都没用到，还是推荐使用DRF，比起你自己用Django撰写的API还是好上许多。
  • 想用轻量化的框架：DRF 虽然包含了很多功能，但核心的view 部份是很简单的。
  • DRF 会被Django 的model 绑住：view 和serializer 都是可选的，没有强制绑定。
  • Django/Python/DRF 太慢：这篇文章会大量讨论效能的部份，基本上都可以透过适当的资料库查询结果暂存、设计良好的HTTP 暂存以及shared server-side cache 来解决。
  • 这篇是作者使用了DRF 并测试其效能以后自己归纳出的一些结论，基本上是推荐使用DRF，算是我看过最完整对DRF 做效能测试的文章了。
  • 一些迷思：
  • 接下来就是非常详细的profiling 步骤与纪录
  • 结论

但这几篇文章其实都有点旧了，大部份都是2015 年的，所以可能不一定符合现在的状况，不确定DRF 在效能方面改进了多少就是。

另外，DRF也有设计一些可以拿来做测试的函式，列在官方的这篇文章里头：Testing - Django REST framework

DRF Docs

DRF Docs 主要功能就是可以根据你在Django REST framework 所使用的View function 直接生出API 文件，有要额外补充的也可以写在View function 的docstring 里头，DRF Docs 会帮你呈现出来，这样就不需要为了API 额外遍写文件，只要docstring 写得够清楚就行，可以节省开发上的时间，也可以让代码更容易被理解。

当时会fork GitHub - manosim/django-rest-framework-docs: Document Web APIs made with Django Rest Framework出来改的主要原因是要改首页的标题。

但实际使用过发现有个需求，就是我想在docstring直接写markdown，觉得应该也有人有这样的需求，所以找了一下。发现有个PR就是在做这件事，不过还没被merge：Added markdown support for endpoint docstrings by mikeengland · Pull Request #117 · manosim/django-rest-framework-docs · GitHub，于是就把这个PR merge进来使用，基本上没啥太大的问题。

撰写这篇文章的时候去追了一下进度，发现已经有另外一个支持markdown的PR被merge了：Add optional markdown for docstrings by rainyday · Pull Request #127 · manosim/django-rest-framework-docs · GitHub，所以现在的DRF Docs应该是有正式支援在docstring可以写markdown这件事，但这个部份我自己没使用过就是。

结论

如果熟Django的人真的可以很快用DRF + DRF Docs弄出一个可以做帐号权限管理的REST API网站，而且因为用上了DRF Docs，所以不会出现程式码和文件不一致的状况。当时撰写完整个网站我也不过花了53 commits 1,806 ++ 761 --，为期大概一个月，学到了没碰过的新东西，成功尝试了Google App Engine Flexible Environment，期间当然也有做其他事。

但如果不考虑快速完成而是考虑效率的话，我大概就不太推荐DRF，虽然不确定目前效能改善到什么地步，如果还是要使用的话可能就要在Database 或架构方面多下点功夫。

因为开发完这网站之后我就没再碰DRF 了，所以这篇文章可能会显得有点过时些，但可以当个参考，毕竟这篇主要目的是纪录给我自己知道到底我把时间花在哪里了。

技术文这种东西真的不太能囤积在草稿啊，能发就要赶快发，不然真的很容易过时。如果是一些跟人比较有关系的文章则大概很难过时，看看技术的长青书基本上都是在讲人的态度或是做事的方法与原则。其实也在思考以后写的一些技术文能否能朝这个方向去多纪录一些。