| @技術/プログラミング

autodoc-generation-flow.png

autodoc を導入して Rails プロジェクトで Request Spec を書くと自動的にドキュメントが更新されるようにした。 autodoc 自体は前々職の頃から利用していて大変お世話になっていた。ただ最初の頃は手元で AUTODOC=1 bundle exec rake spec:requests して手動でドキュメント更新していた。ドキュメントが更新されるかどうかは担当者の心がけ次第なのでよくなかった。

前職では CircleCI を使っていて、デプロイや Asset Precompile など CI でいろいろやるのが当たり前だったので、 Pull Request が Merge されたタイミングでドキュメント生成するように .circleci.yml をカスタマイズしてた。

いま仕事しに行ってるところでは .circleci/config.yml を version 2 にしていて、 version 2 からは workflow の概念が導入されたので、頑張ってシェルスクリプトで条件分岐させたりする必要がなくなった。 .circleci/config.yml は以下のような感じになってる。

version: 2

shared: &shared
  working_directory: ~/app
  docker:
    - image: circleci/ruby:2.4.1-node
      environment:
        PGHOST: 127.0.0.1
        PGUSER: username
        RAILS_ENV: test
        REDIS_HOST: localhost
    - image: circleci/postgres:9.6-alpine
      environment:
        POSTGRES_USER: username
        POSTGRES_PASSWORD: pasword
    - image: redis:3.2-alpine

jobs:
  build:
    <<: *shared
    steps:
      - checkout
      # Restore bundle cache
      - &restore_cache
        type: cache-restore
        key: app-{{ checksum "Gemfile.lock" }}
      # Bundle install dependencies
      - &bundle_install
        run: bundle install -j4 --path vendor/bundle
      # Store bundle cache
      - &save_cache
        type: cache-save
        key: app-{{ checksum "Gemfile.lock" }}
        paths:
            - vendor/bundle
      # Database setup
      - &db_setup
        run:
          name: Database Setup
          command: |
            sudo apt install postgresql-client
            bundle exec rake db:create
            bundle exec rake db:structure:load
      - type: shell
        command: bundle exec rubocop
      # Run rspec in parallel
      - type: shell
        command: |
          mkdir coverage
          COVERAGE=1 bundle exec rspec --profile 10 \
            --format RspecJunitFormatter \
            --out /tmp/test-results/rspec.xml \
            --format progress \
            $(circleci tests glob "spec/**/*_spec.rb" | circleci tests split --split-by=timings)
      # Save artifacts
      - type: store_test_results
        path: /tmp/test-results
      - type: store_artifacts
        path: coverage

  generate-doc:
    <<: *shared
    steps:
      - checkout
      - *restore_cache
      - *bundle_install
      - *save_cache
      - *db_setup
      # Generate document
      - type: shell
        command: |
          AUTODOC=1 bundle exec rake spec:requests
      - run:
          name: Setup GitHub
          command: |
            export USERNAME=$(git log --pretty=tformat:%an | head -1)
            export EMAIL=$(git log --pretty=tformat:%ae | head -1)
            git config --global user.email "${EMAIL}"
            git config --global user.name "${USERNAME}"
      - run:
          command: |
            git add doc
            git commit --quiet -m "[ci skip] API document Update

            ${CIRCLE_BUILD_URL}"
            git push origin ${CIRCLE_BRANCH}

workflows:
  version: 2
  build-and-generate-doc:
    jobs:
      - build
      - generate-doc:
          requires:
            - build
          filters:
            branches:
              only:
                - master

master ブランチでのビルドのときだけ generate-doc という job が実行されるようになっている( master ブランチ以外のビルドではドキュメント生成がスキップされる)。buildgenerate-doc で重複してる部分が多いので YAML のアンカー機能を使って重複を整理しているけど結構長い。 generate-doc ジョブでドキュメントが生成されると勝手に GitHub の master ブランチに対して push する。このときコミットメッセージに [ci skip] という文字列を付けておけば、 CircleCI はビルドをスキップするので延々とドキュメントの自動更新ビルドが走り続けることはない。

おかげでいまはテストさえ書けば、実際の API と同じフォーマットのドキュメントが自動生成されるのでとても便利になったと思う。

ちなみに JSON Schema というのもあって、これは JSON に仕様を書くとドキュメントやらモックサーバーを作ってくれるものらしい。めっちゃ便利そうだけど、ちゃんと使うのにはそれなりに仕組みを整える必要がありそうで手を出していない。 autodoc の作者の r7kamura さんのブログにも書いてある通り、 autodoc の便利なところは以下だと思う。

実際にアプリが生成した内容からドキュメントを生成するため、実装とドキュメントの乖離が少なく抑えられる。 また、テストを書くことの見返りが増えるため開発者がテストを書くのを推進しやすい。

全てがJSONになる - ✘╹◡╹✘

autodoc で master ブランチへの Merge をトリガーにしてドキュメントを自動生成するというポリシーでは、 B/E 側の作業中に F/E の人が API のドキュメントを見られなくて不便だという問題は確かに存在する。しかし JSON Schema で事前に仕様を固めて実装前にモックサーバーやドキュメントを提供できたとして、果たして事前に決めたとおりに B/E も F/E も実装できるのだろうか。きっと作っていく途中で「やっぱりアレはコレに変えたい」みたいのが双方から出てくると思う。

↑の r7kamura さんの記事では他に外の API をモックするダミーサーバーを JSON Schema で作ったりしてる。確かにすでに仕様が固まった外部の何かをモックするサーバーのセットアップなどには便利なのかもしれない。ただいまのところは autodoc での後追いドキュメント自動生成で自分は事足りるかなという感じがしている。

| @ブログ

このブログ( Lokka )の DB は MySQL を使っている。 MySQL のバージョンは 5.7 なので、 column encoding を utf8mb4 、 collation を utf8mb4_general_ci とかにしておけば emoji を使えるかと思ってたけど使えなかった。長らく DataMapper が 対応してないかと思ってたけどリポジトリを覗いてみたら随分前に対応されてた。どうも Lokka 側に問題があるっぽい。

Lokka の DB 接続設定は dsn を URL として記載するようになっている。 DataMapper は ActiveRecord のように Hash オブジェクトを DB 接続の引数に渡せるので、 encoding: 'UTF-8-MB4' をオプションとして渡せるようにしてやればよいっぽいが、いまの Lokka のコードでは encoding オプションを指定できないのでこれではダメっぽい。

ちょっと Lokka 側のコードをいじって encoding オプションを渡すようにしてみたところ無事 emoji が使えるようになったので lokka/lokka に Pull Request 出しておこう ⌨️

| @労働

プログラマーの種類、いろいろあると思う。

  1. ハッカー
    プログラミングが楽しくて、コードさえ書ければあとは何でもいいという人。
  2. OSS プログラマー
    1 と似てるけど、 OSS が楽しくてコードを書いてる人。カンファレンスで登壇したり、技術ブログを熱心に書いたりする。
  3. プロダクト指向プログラマー
    開発だけでなく事業の方向性にも口を出したい人。社長が死んだらいつだって代替ができる、というような気概の人。
  4. サラリーマンプログラマー
    プログラミングは仕事のためと割り切っていて、余暇には一切コードを書かない人。

1 〜 4 のどれか一つに綺麗に分類できるというものではなく、 1 かつ 3 とか、 3 かつ 4 とか、複数にまたがる人もいる。

職業プログラマーになりたての頃、サラリーマンプログラマーしかいない環境で働いて早くそこを抜け出したいと思っていた。プログラマーは会社の最下層で、プロジェクトマネージャーや営業が偉かった。プログラマーの人たちは仕事のために仕方なくプログラミングしてた。

それが嫌で余暇でもコード書くような人たちがいる職場に移ったけど、そこではハッカーや OSS プログラマーがよいプログラマーの代表とされていた(と思う)。自分もそういうのを目指し OSS カンファレンスに登壇したり技術的に中身のあるブログ記事を書いたりしたいと思ったけど、なかなかよいコードは書けないし、結婚して所帯を持つと町内会の草むしりや廃品回収、町内の運動会のテント設営、審判にかり出され、またあるときは子どもの幼稚園に夫婦そろって呼び出されて「お前らは夫婦そろって人間の屑以下だ、心を入れ替えるか幼稚園を辞めるかどっちか選べ」と説教されるなど多忙を極め、勉強会で話したりブログ記事を書いたりということが難しくなった。

一時期は自分は凡人プログラマーなんだろうなぁ、かつて忌み嫌っていたサラリーマンプログラマーと同じなのかなぁ、と将来を悲観していた。この頃は技術的な伸びしろがなくなって学ぶことに対する意欲が失せてしまっていた。

ただ、仕事で失敗プロジェクトを担当してつらい目に遭うことが多く、チームで仕事することだとか、失敗からどう学ぶかとか、その手のことに関してはそこそこ知見が貯まっていった。どうすればチーム開発はうまくいくのか、どういう風に情報を共有すればいいのかなどなど。業務改善のためにちょっとしたスクリプト書いたり、ぶっ壊れて動かなくなってる hubot スクリプトを直したり、 CI のセットアップを頑張ったりと、エンジニアチーム全体の生産性を上げるような落ち穂拾い業務みたいなタスクも好きだった。

いまは自分はチーム開発プログラマーなんだろうなぁと思う。ハッカー気質は皆無じゃないけどそこそこ、 OSS へのコントリビュートも気が向いたときに、プロダクトのことを気にする気持ちもある。どれも中途半端で単独では生産性高くないけどチームで仕事をするときに効能を発揮するタイプ。こんな風に自分が適している役割が分かると仕事がやりやすくなるし、目指すべき方向性のようなものが明確になって将来のことを考える上でも役に立つ。

ベンチャー企業で働く場合は自分のマインドやスキルセットが会社のステージにフィットすることも大事だと思う。もともとはベンチャー企業でも成功して上場しているような会社だとデプロイ時にハンコリレーなどがあってやるべきことをやるべきときにババッとやるのが難しい。そういうのは自分には向いてない。一方で起業したばかりの小さなスタートアップも、自分のような最初から綺麗なコードを書こうとするプログラマーはきっとフィットしない。起業したばかりのスタートアップでは自分たちの事業が社会から求められるかどうか不透明なので、そんな状態でテストがどうだとか CI がどうだとかチーム体制がどうだとかを言うようなプログラマーは必要ない。汚くてもクソコードでもテストコードなんて存在しなくてもいいからとにかく金を生み出すコードを素早く書ける人が向いている。

その意味でいまいる会社は創業当初の価値仮説の検証は済んでいて、これからいかに事業を伸ばしていくかというステージに入っているので、ちゃんとテストを書いたり、 CI を導入して継続的インテグレーションに努めたり、デプロイをいい感じにしたり、情報共有ツールを導入したり、開発チームの組織体制を云々したりといった部分で価値を発揮しやすい。

一握りの本当に優秀なソフトウェアエンジニアってのは受託会社だろうが事業会社だろうがベンチャーだろうが大企業だろうがどこにいたって価値を発揮できるのかもしれない。しかし自分のようなすべてにおいて中途半端なプログラマーは、自分に何ができるのかを理解し自分を必要とする規模とステージの会社を見つけてそこの門を叩くのがよいと思う。もちろん、事業に共感できるとか、チームメンバーとの相性も大事だけど、事業に共感できてもチームのメンバーがいい人ばかりでも、会社の規模やステージが自分を必要としなければ価値を発揮することは難しい。

関連してそうな記事

| @技術/プログラミング

ECS 化していたブログをさくら VPS に戻した。理由としてはお金が高かった。普段、 S3 と Route 53 に払ってる金額の 20 倍くらいの金額になって少ない小遣いでは払えないと思ったので VPS に戻した。ただ AWS で運用して勉強になった点もあった。

まず ECS での運用について知見が得られたのがよかった。 deploy するためには docker builddocker push が必要で、最初はちょっとした修正のためこれやるのは大げさだと思ったが、慣れればそんなでもなかった。ただイメージのビルドをどこでやるかは考えといた方がよさげ。自宅だと高速な光回線があるからよいけど、実家やどこか旅行に行ったときに image をビルドして ECR にプッシュするのはつらい。 GitHub に git push する度に CircleCI でビルドされるような体制を構築する必要があると思った。

CloudFront をウェブアプリケーションの前段に挟む、というのもやってみたけどこれもよかった。 Rails なら Asset Precompile によって静的なファイルへのリクエストはウェブアプリケーションまで届かないようにするのを良くやると思うけど、 Lokka は Sass や CoffeeScript を動的にコンパイルしてクライアントに返すので、 CSS や JS などへのリクエストにも puma のプロセスが消費されてエコではなかった。 VPS 運用時には Nginx を前段に入れて、画像やコンパイル済みの JS / CSS ファイルへのリクエストは puma にプロキシせず直接返していたが、 ECS 化したときに Nginx を挟まなくなったので CloudFront を入れて画像や JS / CSS へのリクエストをキャッシュするようにしてみた。

cloudfront-ecs-image.png

すると puma の負荷が低下し、 New Relic の Appdex が 0.95 前後だったのが 0.99 になった。 ECS で利用していた EC2 コンテナは t2.micro でしょぼいのでサーバーのスペックアップで改善されたわけではない。ということで VPS に戻すときにも Nginx の proxy_cache を使って Sass や CoffeeScript から動的にコンパイルされる CSS / JS をキャッシュするようにしてみた。さすがに CDN のような配信の最適化は実現できないが、以前よりかはかなりましになるはず。

なおセッションを有効にした Rack アプリで Sass や CoffeeScript を動的にコンパイルすると Set-Cookie ヘッダーがセットされてしまう。 Nginx の proxy_cacheSet-Cookie ヘッダーがセットされてるとキャッシュをしないので、

proxy_ignore_headers Set-Cookie;
proxy_hide_header Set-Cookie;

などとしてやる必要がある。

今後仕事でも ECS 化を行う予定があるので得られた知見を有効活用していきたい。