Webソケットを使用してRESTフレームワークを作成した方法の物語

この記事では、次のRESTフレームワーク（Python 3用）について説明します。この機能の特徴は、クライアントとサーバー間でデータを交換するためにWebソケットを使用することです。 アイデアがどこから来たのか、Python用の最初のライブラリを書くときに何を扱わなければならなかったのか、そしてそれから何が出てきたのかについて、私はさらに語ります。









この記事に興味がある人のために-Catの下に行ってください。

1.プロジェクトのアイデア

このアイデアは2015年4月中旬に生まれました。同僚と仕事をしていて、同僚と一緒にオフィスで仕事をしています。 プログラミングに直接関わっている間に、どういうわけか自分を楽しませるために、さまざまな興味深いPythonプロジェクトについて話すことにしました。 コミュニケーションの過程で、彼らはどういうわけか自発的に自分のプロジェクトのトピックに取り組み、プロジェクトでさらに使用するのに興味深いものにアプローチしました（必ずしも仕事に関連しているわけではありません）。 直接議論するとき、問題なく双方向にデータを転送できるWebソケットを使用するかなり「柔軟な」フレームワークを用意するのが良いというアイデアが生まれました。 各リクエストはJSON形式で提供され、RESTおよびHTTPプロトコルを使用する際によく知られているヘッダーが含まれています。 また、快適な追加機能として、何らかのイベント/タイムアウト時にサーバーからクライアントに通知（通知）を送信する機能を提供します。



当然のことながら、このような長い議論の後、私はこのアイデアを実現することにしました（そしてなぜそうではないのですか？）。 自身の興味、熱意、そして第3 Python'aのエコシステムの開発に役立つ何かをしたいという願望は、すぐにビジネスに取りかかるための特別な動機を与えました。

2.目標を設定する

私自身、個人的には、前述の内容に加えて、ライブラリを作成するときに自分の努力に集中することが決定されたいくつかの追加ポイントを強調しました。

• クライアント要求を処理するときにasyncioを使用してみてください
• 1-2個以下の依存モジュール（小さいほど良い）
• 難しすぎて理解できないはずです。
• 使いやすさ（Django REST、Flaskフレームワークを参照してください。これはかなりシンプルで柔軟です）
• プログラマは、必要なときにほぼすべてのコンポーネントを交換できます

当然、最初のバージョンでリリースすることは、開発プロセスを離れることはなかったので、上記のすべては完全に非現実的でした。そのため、少し簡略化するために、すべてを小さな「ピース」に分解することにしました。 それらを作成し、テストし、リリースし、同様のスキームに従って残りを実行します。 最初に、ライブラリにとって最も重要なもの（ルーティング、ビュー、認証など）を記述し、後で可能な限り新しい機能を追加します。

3.開発の準備：Aiohttp対Gevent対Autobahn.wsの選択

開発は2015年4月末頃に開始されました。プロジェクトの作業を何らかの形で促進するために、既製のソリューション（または以前は予想していなかった既存のライブラリ）の検索を開始しました。 私と似たようなアイデアを持っているライブラリはありませんでした。 必要なコンポーネントのほとんどは、行われているすべてのプロセスの独自の理解に基づいて、独立して作成する必要があるため、これはタスクの複雑化につながりました。



私は、Webソケットを使用できるようにするライブラリーから直接始めることにしました。 当時、aiohttp、gevent、autobahn.wsなどのパッケージがいくつか見つかりました。 各ライブラリにはそれぞれ長所と短所がありますが、まずは、特に必要のない場所で自転車を再び駐車する必要がないように、機能とコードの再利用の可能性から始めました。



Aiohttpは、asyncio標準ライブラリに基づいたsvetlovによって開発されたWeb開発ライブラリです 。 このライブラリを使って本当に素晴らしい経験をしたとは言えませんが、多くのことが非常にクールに行われていることは注目に値します。 ただし、Webソケットを使用した提案されたソリューションは、やや低レベルのように思えました（ただし、場合によっては本当に便利です）。 私はもう少し抽象化することを望んでいました（例えば、クライアント/サーバーがonMessageやsendMessageのようなメソッドを持っているgevent-websocketやautobahn.wsのように、イベント指向のTwistedフレームワークのメソッドに似ています）。 残りは、図書館は美しいです。



最初のレビューでのGeventは、注目を集めた最初のパッケージの1つでした。 また、すぐにそれを使用するというアイデアは拒否されました。プロジェクトが開始されたとき（2015年4月）、geventはPython言語の3番目のブランチに移植されていませんでした。 ただし、すべて同じように移植された場合は、gevent-websocket拡張機能を使用して使用すると、すべてが非常にうまく機能します。 このライブラリを書いている時点では、このライブラリはすでに3番目のブランチをサポートしていますが、今はそれを切り替えても意味がありません。



Autobahn.wsは、小さなペットプロジェクトを作成する際に数回対処しなければならなかったライブラリであり、使用に関してはすでに最小限の経験しかありません。 かなり良いコミュニティに加え、ライブラリの作成者は、問題が発生した場合にいつでも支援する準備ができています（たとえば、Twisted + wxPythonと組み合わせることができなかったとき、Tobiasはこれをどのように行うことができるかを非常によく説明しました）。 最新バージョンはasyncioと互換性があり、必要な場所にデコレータを追加するだけです。 もう1つの優れた機能は、 RFC6455への準拠と、着信/発信データのチェックの可用性です（到着したか、UTF-8エンコードで送信されたかは非常に便利だと思います）。 したがって、将来のライブラリの基礎として使用することが決定されました。

4.開発中に発生した問題

ライブラリの最初のバージョンを書くとき、私は単に多くのタスクにアプローチする方法を知りませんでした。 少し考えてから、サーバーがクライアントからの着信要求をどのように処理するかというパスに沿って、実装と一緒に進むことにしました。



1）リクエストを受信した

2）必要なデータが到着したことを確認しました。これに基づいて、リクエストの処理方法（操作の種類、連絡先など）が明らかになります。

3）着信要求（特定のエントリポイントと呼び出されるメソッド）に一致するハンドラを探しています。 何も見つからなかった場合、エラーを返します。 すべてが正常であれば、適切なハンドラーを選択し、受け取った引数をそれに渡します

4）生成された応答は、特定の形式（JSON、XMLなど）につながりました

5）クライアントに回答を返しました



理論的には、すべてが非常に単純に聞こえますが、実際には、すべてがまったく逆であることが判明しました。 私に起こった唯一のことは、高レベルの抽象化から低レベルの抽象化に行くことでした。 つまり、Autobahn.wsとasyncioループを使用して次のように作業しました。



1）「ファクトリー」のインスタンスを作成します。これは、asyncioループを使用し、着信接続を受け入れてそれらを処理します。 「ハンドシェイクプロセス」が完了すると、クライアントからリクエストを受信して​​処理する準備が整います。



2）特定の形式でクライアントからリクエストを受信しました。 この場合、次のようにJSONの形式で受信します。

{ 'method': 'POST', 'url': '/users/create', 'args': { 'token': 'aGFicmFoYWJyX2FkbWlu' }, 'data': { 'username': 'habrahabr', 'password': 'mysupersecretpassword', } }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

このJSONの構造はかなり単純です。 クライアントは、私たちにとって重要ないくつかのパラメーターを定義するだけで十分です。

• method-リソースに対する操作のタイプ（HTTPで行われる方法と同様）。
• url-処理したいリソースへのパス。
• args（オプション）-サーバーに送信されるパラメーターのセット。 最も近い類推は、「？」を使用したHTTP要求URLで定義されたパラメーターです。 「 habrahabr.ru/?page=2&paginate_by=25 」のような「＆」文字。 これは、既製のデータのリスト（たとえば、特定のグループを割り当てる必要があるユーザーの識別子）、または要求処理中にサーバー側で使用されるフィルターの単なる引数のセットです。
• データ（オプション）-リソースを操作するときに使用されるデータのセット。 一般に、これはHTTPリクエストの本文に類似したものであると想定できます。
• event_name（オプション）-データがどのエンドポイントから返されたかを理解できる一意の識別子。

この種のリクエストについて、サーバーは受信を期待しています。 必要な引数がない場合は、すぐに説明します（たとえば、メソッドを追加するのを忘れました）。 それ以外の場合は、リストをさらに進めます。



3）そのため、要求はサーバーに配信され、正しい形式で正しいものになります。 次に、それに応じて処理し、答えを返します。 しかし、これには何が必要ですか？ 私の観点からは、初めて、ルーティングシステムで特定のURLに必要なハンドラーを登録するだけで十分です。これにより、対応する応答が生成され、JSON、XML（またはその他の形式）に変換され、クライアントに返されます。



この時点で、ルーティングに注意を向けたいと思います。 これは非常に重要なポイントです。たとえば、現在のユーザーのリスト（「/ users /」など）を取得するために、ある固定URLでアクセスを提供したいからです。 一方、「/ users //」という形式のURLを介してアクセスすることもできますが、これにはユーザーに関する詳細情報が必要です。 つまり、最初のタイプのルーティングは単純で静的、2番目のタイプは動的であると見なします。これは、リクエストからリクエストへと変化するリソースへのパスにパラメーターがあるためです。



この問題を解決するには、正規表現が役立ちます。 リソースパスが宣言されるたびに、たとえば：

 router = SimpleRouter() router.register('/auth/login', LogIn, 'POST') router.register('/users/{pk}', UserDetail, ['GET', 'PATCH'])
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

そのようなリソースへのパスを分析します。 そして、特定のタイプのリクエストのみを、指定されたパスに沿ってのみ処理するエンドポイントを作成します。 このリソースへのリクエストが到着すると、キーをパス、値をハンドラーとするディクショナリを通過するだけで十分です。 要求の受信時に動的パスが検出され、必要なハンドラーが見つかった場合、検出された動的パラメーターを要求の処理場所に転送して、キーでオブジェクトを取得したり、このパラメーターを使用して他の操作を実行したりできるようにします。



そしてもちろん、リクエストが存在しないURLに到達した場合を考慮します。 彼にとっては、具体的な説明とともにエラーを返すだけで十分です。



4）素晴らしい、今何かがクリアされました。 必要なパスとそれらのハンドラーを見つけ、パラメーターを見つけて転送するためにレギュラーを使用できます（動的パスがキャッチされた場合）。 次に、JSONで指定されたメソッドパラメーターを調べて、ビューから対応するクラスメソッドを見つけます。 存在しない場合は、すぐにそれについて話し、操作を実行しません。 それ以外の場合は、検出されたメソッドを呼び出して回答を作成します。



5）次に、データ（エラーのある場合を含む）を特定の形式にシリアル化します。 デフォルトでは、すべてがJSON形式に変換されます。



6）生成された応答をWebソケット経由でクライアントに転送します。



このサンプル計画によると、リリース1.0の前に続きました。 独自のビュー、ルーティングシステム、およびその他の興味深い機能を作成することは非常に興味深いことでした。 最初のリリースを作成する過程では、このpet-projectの開発中に、構成のあるモジュールが必要でした（この場合、Djangoのモジュールに似たモジュールでした）。 または、たとえば、私にとって非常に必要な認証により、ミドルウェアおよびJSON Web Tokenモジュールのサポートが徐々に実装されました。 前に述べたように、私たちはすべての種類のモジュールを自分で行い、余分なものを引っ張ろうとしないでください。



何らかの形で、「次の自転車」と書いてくれたので、追加の労力と時間のコストがかかりました。 率直に言って、私はこの方法で行ったことをまったく後悔していません。書き込み、デバッグ、および定期的な微調整に費やされた時間が自分自身を感じているためです。



最初のバージョンを書くとき、コードの記述とデバッグがかなりうまくいったら、バージョン1.1を実装するときに、長い間デバッグにとどまりました。 コードの記述と移植は、何が起こっているのかを検索して詳細に分析するほど時間はかかりませんでした。例えば：



1）「内部」で何がどのように発生しているかについてのDjango RESTフレームワークのソースコードベースの分析：特定のオブジェクトの書き込みまたは読み取りを行う場合の処理​​。 受信したフィールド（および他のモデルとの接続がある）と、シリアル化/非シリアル化の必要性をいつ、どのように理解するか。



2）SQLAlchemyモデルのシリアル化。DjangoRESTコードとDjango ORMの間で発生する方法に似ています。



3）既に作成されたAPIを介して何らかのオブジェクトへのパスを取得できるように（受信したURLを使用して一部のデータを読み書きできるように）ルーティングで作業する機会を持つ。



機能のこの部分を開発するとき、ライブラリのソースコード、Django REST（これは主に次のバージョンの基礎でした）、およびSQLAlchemy + marshmallow-sqlalchemyライブラリのソースコードの両方が、すべてのアイデアを実現するのに役立ちました。



多くのリソースが消費されましたが、最終結果はすべてのコストを完全に正当化しました-これで、Django RESTで使用していた方法でSQLAlchemyを操作できるようになりました。 データの操作は同じであり、実質的に大きな違いはありません。 実質的に自分自身を再学習する必要がないことは素晴らしいことです。アクセス可能なAPIは、多くの点でDjango RESTで使用されているものと同じです。

5.プロジェクトの現在のステータス

現在、ライブラリには次の機能があります。

• ルーティング
• 関数ベースおよびクラスベースのビューのサポート
• JSON Web Tokenによる認証（少し制限されていますが）
• Django Frameworkの設定と同様の設定を持つファイルのサポート
• 送信されたメッセージの圧縮（ブラウザでサポートされ、必要な拡張機能がインストールされている場合）
• DjangoおよびSQLAlchemy ORMモデルのシリアル化
• SSLサポート

6.使用例

簡単な例として、次のコードを使用してユーザーとメールアドレスを操作できます。 SQLAlchemy ORMを使用して説明したテーブルを開始しましょう。

 # -*- coding: utf-8 -*- from sqlalchemy.ext.declarative import declarative_base from sqlalchemy import Column, Integer, String, ForeignKey from sqlalchemy.orm import relationship, validates Base = declarative_base() class User(Base): __tablename__ = 'users' id = Column(Integer, primary_key=True) name = Column(String(50), unique=True) fullname = Column(String(50), default='Unknown') password = Column(String(512)) addresses = relationship("Address", back_populates="user") @validates('name') def validate_name(self, key, name): assert '@' not in name return name def __repr__(self): return "<User(name='%s', fullname='%s', password='%s')>" % (self.name, self.fullname, self.password) class Address(Base): __tablename__ = 'addresses' id = Column(Integer, primary_key=True) email_address = Column(String, nullable=False) user_id = Column(Integer, ForeignKey('users.id')) user = relationship("User", back_populates="addresses") def __repr__(self): return "<Address(email_address='%s')>" % self.email_address
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

次に、これら2つのモデルに適したシリアライザーについて説明します。

 # -*- coding: utf-8 -*- from app.db import User, Address from aiorest_ws.db.orm.sqlalchemy import serializers from sqlalchemy.orm import Query class AddressSerializer(serializers.ModelSerializer): class Meta: model = Address fields = ('id', 'email_address') class UserSerializer(serializers.ModelSerializer): addresses = serializers.PrimaryKeyRelatedField(queryset=Query(Address), many=True, required=False) class Meta: model = User
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

多くの人が気づいたように、ユーザーをシリアル化するためのクラスを定義した場所で、アドレスフィールドが指定され、PrimaryKeyRelatedFieldクラスのコンストラクターで引数queryset = Query（Address）が指定されています。 これは、SQLAlchemy ORMのシリアライザーがアドレスフィールドとテーブルの間に関係を構築し、シリアル化中にこのクラスに主キーを渡すことができるようにするために行われます。 ある程度、これはDjangoフレームワークのQuerySetに似ています。



次に、利用可能なAPIを使用してこれらのテーブルのデータを操作できるようにするビューを実装します。

 # -*- coding: utf-8 -*- from aiorest_ws.conf import settings from aiorest_ws.db.orm.exceptions import ValidationError from aiorest_ws.views import MethodBasedView from app.db import User from app.serializers import AddressSerializer, UserSerializer class UserListView(MethodBasedView): def get(self, request, *args, **kwargs): session = settings.SQLALCHEMY_SESSION() users = session.query(User).all() data = UserSerializer(users, many=True).data session.close() return data def post(self, request, *args, **kwargs): if not request.data: raise ValidationError('You must provide arguments for create.') if not isinstance(request.data, list): raise ValidationError('You must provide a list of objects.') serializer = UserSerializer(data=request.data, many=True) serializer.is_valid(raise_exception=True) serializer.save() return serializer.data class UserView(MethodBasedView): def get(self, request, id, *args, **kwargs): session = settings.SQLALCHEMY_SESSION() instance = session.query(User).filter(User.id == id).first() data = UserSerializer(instance).data session.close() return data def put(self, request, id, *args, **kwargs): if not request.data: raise ValidationError('You must provide an updated instance.') session = settings.SQLALCHEMY_SESSION() instance = session.query(User).filter(User.id == id).first() if not instance: raise ValidationError('Object does not exist.') serializer = UserSerializer(instance, data=request.data, partial=True) serializer.is_valid(raise_exception=True) serializer.save() session.close() return serializer.data class CreateUserView(MethodBasedView): def post(self, request, *args, **kwargs): serializer = UserSerializer(data=request.data) serializer.is_valid(raise_exception=True) serializer.save() return serializer.data class AddressView(MethodBasedView): def get(self, request, id, *args, **kwargs): session = settings.SQLALCHEMY_SESSION() instance = session.query(User).filter(User.id == id).first() session.close() return AddressSerializer(instance).data class CreateAddressView(MethodBasedView): def post(self, request, *args, **kwargs): serializer = AddressSerializer(data=request.data) serializer.is_valid(raise_exception=True) serializer.save() session.close() return serializer.data
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

現時点では、オブジェクトを操作するための個別のビューと、オブジェクトのリストを個別に作成しています。 MethodBasedViewから継承されたこれらの各サブクラスは、使用される特定のハンドラーを実装します。 リクエストの各タイプ（get / post / put / patch /など）に対して、独自のハンドラーが作成されます。



最後のステップは、このAPIを登録し、外部からアクセスできるようにすることです。

 # -*- coding: utf-8 -*- from aiorest_ws.routers import SimpleRouter from app.views import UserListView, UserView, CreateUserView, AddressView, \ CreateAddressView router = SimpleRouter() router.register('/user/list', UserListView, 'GET') router.register('/user/{id}', UserView, ['GET', 'PUT'], name='user-detail') router.register('/user/', CreateUserView, ['POST']) router.register('/address/{id}', AddressView, ['GET', 'PUT'], name='address-detail') router.register('/address/', CreateAddressView, ['POST'])
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

実際、ここですべての準備が整いました。サーバーを起動してクライアントを介して接続するだけです（Python + Autobahn.ws、JavaScriptを使用するなど、多くのオプションがあります）。 たとえば、Python + Authobahn.wsを使用したいくつかの簡単なクエリを表示します（事前に予約しますが、クライアントの例は完璧ではありません。ここでのタスクは、これを行う方法を示すことです）。

 # -*- coding: utf-8 -*- import asyncio import json from hashlib import sha256 from autobahn.asyncio.websocket import WebSocketClientProtocol, \ WebSocketClientFactory def hash_password(password): return sha256(password.encode('utf-8')).hexdigest() class HelloClientProtocol(WebSocketClientProtocol): def onOpen(self): # Create new address request = { 'method': 'POST', 'url': '/address/', 'data': { "email_address": 'some_address@google.com' }, 'event_name': 'create-address' } self.sendMessage(json.dumps(request).encode('utf8')) # Get users list request = { 'method': 'GET', 'url': '/user/list/', 'event_name': 'get-user-list' } self.sendMessage(json.dumps(request).encode('utf8')) # Create new user with address request = { 'method': 'POST', 'url': '/user/', 'data': { 'name': 'Neyton', 'fullname': 'Neyton Drake', 'password': hash_password('123456'), 'addresses': [{"id": 1}, ] }, 'event_name': 'create-user' } self.sendMessage(json.dumps(request).encode('utf8')) # Trying to create new user with same info, but we have taken an error self.sendMessage(json.dumps(request).encode('utf8')) # Update existing object request = { 'method': 'PUT', 'url': '/user/6/', 'data': { 'fullname': 'Definitely not Neyton Drake', 'addresses': [{"id": 1}, {"id": 2}] }, 'event_name': 'partial-update-user' } self.sendMessage(json.dumps(request).encode('utf8')) def onMessage(self, payload, isBinary): print("Result: {0}".format(payload.decode('utf8'))) if __name__ == '__main__': factory = WebSocketClientFactory("ws://localhost:8080") factory.protocol = HelloClientProtocol loop = asyncio.get_event_loop() coro = loop.create_connection(factory, '127.0.0.1', 8080) loop.run_until_complete(coro) loop.run_forever() loop.close()
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

ここで、サンプルのソースコード全体をさらに詳しく見ることができます 。

7.さらなる開発

現在のライブラリ機能を拡張する方法については、かなりの数のアイデアがあります。 たとえば、次の分野でこのモジュールを開発できます。

• 通知サポート
• ブラウザを介してAPIドキュメントを表示する（おそらくSwaggerのプラグインとして）
• APIテストモジュール
• PythonおよびJavaScriptのクライアント
• PonyおよびPeewee ORMのサポート

繰り返しになりますが、多くの機能は1つのリリースではなく、異なるリリースで計画されていることを思い出させてください。 これは意図的に行われたものであり、極端なものから別のものへと急いで行かないように、並行して何かをします。 そして、私にとってもあなたにとっても簡単です。

8.そして結論として...

独自のライブラリを作成した経験がないにもかかわらず、初めてかなり良い結果になったと思います。 そして、Python言語の開発に非常に強く貢献します（たとえ小さなものでも）。 費やされた時間に驚かないでください：すべてが自由時間で定期的に行われます（そして継続されます）（1つのプロジェクトでの定期的な作業は非常に疲れますが、同時に複数の方向で開発したいため）。



何らかの形で、このライブラリに関するすべての提案、アイデア、改善点をコメント（またはGitHubのリクエストプールの形式）で聞いてうれしいです。 ライブラリや実装の機能に関するご質問はお気軽にお寄せください。フィードバックをお待ちしております。



上記のすべてのコードとaiorest-wsライブラリのソースは、 GitHubで表示できます。 サンプルは、プロジェクトのルート、examplesディレクトリにあります。 ドキュメントはここで見ることができます 。