Misoca の PDFテスト

こんにちは、弥生の日高 @hidakatsuya です。普段は クラウド見積・納品・請求書サービス「Misoca」 の開発に携わっています。

Misoca には、作成した請求書などの帳票を PDF としてダウンロードするだけでなく、PDF の内容を印刷したり、郵送したり、FAX として送信するなど、PDF が関連する機能が多くあります。そして、毎日非常に多くの PDF が Misoca 上で生成されています。

今回は、そんな Misoca の PDF をどのようにテストしているのかについてまとめたいと思います。

Misoca の PDF

本題に入る前に、Misoca で扱っている PDF についてもう少しだけ説明しておきます。

  • 請求書・納品書・見積書・注文書・注文請書・検収書・領収書の7種類の PDF がある
  • 請求書・納品書・見積書は複数のテンプレートを提供している
  • 執筆時点で、請求書には14種類、見積書・納品書にはそれぞれ2種類のテンプレートがある

また、2020年以降での PDF に関するリリース(ある程度の規模の機能追加や変更)回数を集計したところ、24回のリリースを実施していました。月に平均2回程度、PDF に関するリリースをしていたということになります。

Misoca の PDFテスト

これだけの種類の PDF をこの頻度で安全にリリースするためには、自動テストの仕組みは不可欠です。Misoca でも、CI として PDF 生成の結果を自動テストする環境を整えています。

  • テストケースごとに生成した「実際の PDF」と「期待するPDF」と比較し、一致しない場合は失敗として差分結果も出力する
  • 帳票の種別ごと、テンプレートごとに 8~25 のテストケースがあり、合計で 482 ケースある
  • それなりに重いので、リリーステスト*1pdf_spec_*ブランチの push 時にテストを実行する

これら一連のテストを Misoca チームでは「PDF spec」と呼称しています。

PDF spec

PDF spec は、他のテスト同様に RSpec で動作します。テストコードは spec/pdf/ に配置し、あくまで Misoca の spec の一部に過ぎません。PDFの比較には、diff-pdf を使い、PDF ファイルを直接比較することでテストします。

構成と実装

請求書のスタンダードテンプレートの spec を例に詳細を説明します。

Rails.root/
 ├── app/
 :
 ├── spec/
      ├── pdf/
      :    ├── invoice/STANDARD/
           :    ├── expected
                │    ├── general_usage.pdf
                │    ├── max_input.pdf
                │    :
                └── pdf_spec.rb

pdf_spec.rb がテスト本体で、expected/ 配下の general_usage.pdf などがテストケースの「期待するPDF」です。

pdf_spec.rb は、実際とは少し異なりますが、概ね次のような実装になっています。

RSpec.describe Invoice, type: :pdf do
  include_context 'pdf spec'

  it_behaves_like 'pdf spec: general usage'
  it_behaves_like 'pdf spec: max input'
  ...
end

「期待するPDF」との比較テストは include_context 'pdf spec' の中で行なわれます。

it { expect(subject).to match_pdf(expected_pdf_path, output_diff: diff_pdf_path) }

match_pdf で PDF の比較が行われ、一致しない場合はテストは失敗します。

この時、後述のオプションを指定すると、diff_pdf_path で指定したパスに差分のPDFが出力されます。差分は、次のように変更箇所がハイライトされた普通の PDF ファイルとして出力されます。これは diff-pdf の機能です。

f:id:hidakatsuya:20220222115124p:plain
領収書PDFのタイトルのフォントサイズを大きくした場合の差分PDF

なお、この match_pdf Matcher は、筆者作の pdf_matcher-testing gem で定義されています。*2

PDF spec の機能と bin/pdf_spec コマンド

前述の通り、PDF spec は RSpec の example の一部に過ぎないため、bin/rspec spec/pdf/invoice/STANDARD で実行することができますが、手元での開発時は専用のコマンド bin/pdf_spec を使って実行します。

以下は bin/pdf_spec の実際のコマンドヘルプです。

$ bin/pdf_spec
Usage: pdf_spec [OPTIONS] specpath

OPTIONS:
  --verbose          テスト結果の差分PDFと結果PDFを tmp/pdf_spec/ に出力する
  --update_expected  期待PDF(expected.pdf)を結果PDFで更新する。差分PDFも出力する

  詳細は spec/support/shared_context/pdf/pdf_spec_shared_context.rb のコメントを参照
  その他、rspecコマンドに渡す任意のオプションを指定できます

specpath:
  spec/pdf/ 配下の spec ファイルを指定します

Examples:
  $ bin/pdf_spec --verbose spec/pdf/invoice/STANDARD
  $ bin/pdf_spec --update_expected -fd -e "min input" spec/pdf/invoice/STANDARD ...

上記の通り、このコマンドは、単に PDF spec を簡単に実行するだけではなく、PDF の変更を行う際の PDF spec に伴う開発フローを助ける役割も担っています。

PDF に差分が生じていないかを確認する

まず、単に spec を実行すると、PDF を比較し差分が生じていないか(壊していないか)を確認できます。

$ bin/pdf_spec spec/pdf/invoice/

PDF の結果と差分が意図したものか確認する

そして、--verbose オプションを指定することで、テストケースの実際の PDF と期待する PDF との差分(あれば)を tmp/pdf_spec/ に出力して、PDF への変更内容が期待通りかを確認することができます。

$ bin/pdf_spec --verbose spec/pdf/invoice/

期待する PDF の内容を更新する

最後に、意図通りの変更ができていることを確認したら、--update_expected オプションを指定し、期待するPDFを変更後の内容で更新することができます。更新された「期待するPDF」を push して一連の実装は完了となります。

$ bin/pdf_spec --update_expected spec/pdf/invoice/

なお、このコマンドの実装は非常にシンプルなものとなっています。以下は bin/pdf_spec の一部です。

for arg in "$@"; do
  case $arg in
    "--verbose"|"--update_expected")
    mode=${arg#--}
    ;;

    *)
    args+=("$arg")
    ;;
  esac
done

if [[ ${#args[@]} -eq 0 ]]; then
  exit_with_usage
fi

PDF_SPEC=$mode bin/rspec "${args[@]}"

実は、 verboseupdate_expected などの機能は、spec 側で PDF_SPEC 環境変数の値を読み取って実現しています。そのため、bin/pdf_spec は、--verbose などのオプションを解釈して、PDF_SPEC 環境変数に適切な値をセットし、bin/rspec を実行しているだけです。

これまでの改善・工夫

最後にこれまで行なってきた改善や工夫をいくつか紹介します。

PDF spec のテストケースが多過ぎてテストが遅く、テストケースのメンテも大変

当初、請求書だけでテストケースは 2000 を超えていました。網羅性が高く安心感はありますが、通常のビルドで実行するには、あまりにも実行時間もリソースも占有しすぎていました。

これは、シンプルに「テストケースを減らす」ことで改善した形ですが、まず「PDF spec の責務」を定義することから始めました。

  • 関心のあるもの
    • PDFの表示が意図したものか
    • 表示がくずれていないか、表示されるべきところに正しく表示されているか
  • 関心のないもの
    • PDFを出力する過程や出力した後での状態の変化
    • 例えば、金額の計算結果の確認は PDF spec の責務ではない

そして、この責務に則り、PDF spec (PDF そのものの比較) でカバーすべきものと、PDF 生成の実装 (PDF生成の過程のロジックなど) の spec でカバーすべきものへ整理することで、PDF spec のテストケースを全種類で 480程度に圧縮しました。

目視では判別できない差分でテストが失敗する

稀に、差分の PDF をみても差分を確認できないケースが発生したことがありました。この手のビジュアルリグレッションテストではよくあるやつですね。

これは、diff-pdf の v0.4v0.5 で追加された --channel-tolerance--dpi オプションを使って、検知する差分の閾値を調整することで解決できます。

おわりに

今回は、Misoca の PDF を支える PDF spec について書きました。

PDF に問題があった場合の影響は大きく多岐に渡ります。PDF spec の整備によって、常に一定の PDF の品質が担保されことにより、PDF の変更に対しての心理的な安心感も確保されたことは非常に大きいと思います。

一方で、現在の仕組みは、CI だけでなく、手元でも手軽に実行でき非常に便利な反面、大量のPDFファイル(期待するPDF)をリポジトリに保存している*3 点や、通常の spec に比べるとどうしても重く遅い処理のため、CI 全体の時間・リソースを少なからず圧迫してしまっている点など、課題点も多く残るのが現状です。

今後も、reg-suit の導入など、より良い環境を模索していきたいと思っています。

お知らせ

弥生では一緒に働く仲間を募集しています!

herp.careers

*1:Misoca では基本的に毎日午前午後の2回リリースします。

*2:その他関連するものとして、PDFの比較を行う pdf_matcher gem や GitHub Actions で diff-pdf をインストールする setup-diff-pdf action などもあります。

*3:Git LFS として扱っています。

もくテク「新年の抱負を語ろう!LT」を開催しました

f:id:tatsuki_iida:20220124111415j:plain

こんにちは、情シスエンジニアの飯田です。

寒さの厳しい時期になりましたね。私の部屋はロフト付きのため天井が高く、エアコンの暖房が上に流れてしまうため冬の寒さが課題だったのですが、今年から電気毛布とフットウォーマーを導入してリモートワーク環境が快適になりました。電気代も安いみたいなので嬉しいです。

さて今回は、先日1月20日(木)に開催したもくテクの報告記事となります。
イベントページはこちら(開催は終了しています)。

mokuteku.connpass.com

テーマは「新年の抱負を語ろう!LT」

2022年最初の開催ということで、テーマは新年らしく今年の抱負についてです!
デスクトップ・クラウドアプリ開発に新規サービス開発、情シス、QAと様々なチームのエンジニアに登壇いただき、新年の抱負を発表してもらいました。

技術の話がメインになると思いきや、仕事に関することからプライベートのことまで様々な抱負や目標が語られましたので、カテゴリー分けしてご紹介したいと思います。

仕事で成果を出すぞ!

最初は仕事に関するものです。各チームで今年の開発スケジュールや山場が見えているので、そこで成果を出せるよう勉強を頑張りたいという発表がありました。

この目標に対する手段として挙げられるのが資格の取得で、情報処理技術者試験やAWS認定、さらには弥生らしく簿記を目指している方もいました。資格の勉強は知識の体系的な習得や整理に役立ち、見事合格できれば自信にも繋がるので、有効な方法だと思います。

趣味にも力を入れるぞ!

仕事も大切ですが、プライベートを充実させることも重要です。ということで積読を消化したり自作のアプリを作成したりと趣味に関する抱負もありました。

弥生の開発本部ではリモートワークがすっかり定着しており、通勤がなくなって自由に使える時間が増えたという人も多いと思います。コロナ禍という厳しい状況が続いていますが、その中でも楽しめる趣味があると生活も充実しますね。

生活習慣を変えるぞ!

仕事や趣味を問わず、それぞれ達成したい目標のために生活習慣を変えようという人もいました。エンジニアらしく自分で情報収集アプリを作ってチェックする習慣を身につけたり、ダイエットのために運動を始めたりと、こちらも手段は様々です。

そういえば弥生では2022年1月からフレックスタイム制が導入されました。リモートワークによって働く場所が選択できるようになり、フレックスによって働く時間にも自由度が生まれました。これを活かして家事や育児を頑張るという社員もおり、従来よりもより働きやすい環境になることが期待されます。

仕事に遊びごころを!

ちょっと変わった抱負もありました。ITエンジニアといえば設計書や手順書が欠かせませんが、お堅い文章ばかりなので時候の挨拶や超感覚的な表現を取り入れてほっこりしようという、遊びごころ満載の内容でした。正確さの求められるドキュメントで超感覚的とはこれ如何に?と思いましたが、発表では次のような例がありました。

  • 野山がサクラ色に染まり始める今日この頃、初期設定入力の画面設計です。
  • おいおい、あと何回させるつもりだ?とあきれる程、Windows Updateします。

なるほど、このような表現があると気持ちも和みそうですね!…あ、レビュアーさん、この人のドキュメントのレビューは念入りにお願いします(笑)

今年ももくテクを盛り上げていきます!

最後にもくテク運営の抱負を簡単に書きたいと思います。

もくテクは昨年5月にオンライン形式に変えて再開し、これまでで9回実施してきました。今年もトレンドの技術や話題を取り入れ、もくテクを盛り上げていきたいと思いますので、今後もよろしくお願いいたします!

え、私自身の抱負は何かって?…そろそろクロージングのお時間ですので今回はこの辺にしておきたいと思います(逃走)

次回のご案内

次回の開催は2月17日(木)で、「弥生って、実は機械学習もやってるんです!」がテーマです。

弥生が提供するサービスには機械学習を用いた機能があり、自社で研究開発を行っています。
どのような仕組みなのか、研究開発はどうやっているのか、運用はどうしているかなどの裏側について紹介しますので、機械学習に興味のある方はぜひご参加ください!

mokuteku.connpass.com

採用について

弥生では、幅広いポジションでいっしょに働く仲間を募集しています!
ポジション等の詳細については以下のサイトをご覧ください。

herp.careers

Dockerの有償プランを契約して運用するまでの話

こんにちは。弥生の内山です。
みなさまご存知の通り、2022年1月31日以降、一定以上の規模の組織でDocker Desktopを利用するには有償プランの契約が必要となります。

www.docker.com

弥生では、検討の結果、Dockerを利用する開発者全員分のライセンスを購入し運用することにしました。
しかし、実際に有償プランを使おう!となったとき、具体的に何をしたらよいのかという情報がWeb上にほとんど見つからず、手探りで作業を進めることになりました。
現時点で、ようやく運用の形が見えてきたため、この記事では契約から運用までの具体的な考慮ポイントをご紹介したいと思います。
無償利用の猶予期間終了が迫っている中、有償プランの利用について困っている方の助けになれば幸いです。

(なお、この記事は2022/01/20時点で弥生内で検討・試行した内容に基づいて作成したものであり、Docker社の提供するサービスについて正確な情報を提供することを目的としたものではありません。契約を行われる際は十分な調査を行った上でご判断ください)

なぜ有償プランを契約するのか

Docker Desktopが使いたい

有償プランを契約する目的は、開発メンバーがDocker Desktopを使えるようにすること、ほぼそれだけです。
「Docker Desktopを利用せず、無償で利用できるツールの範囲でDockerを使い続ければよいのでは?」という考え方もあります。
実際、Web上にはDocker Desktopを使わずにDockerを使い続けるための手順が多数見つかります。
そのようにして有償プランを契約せずにDockerを利用し続けるという選択はありだと思います。
ですが、我々は有償プランを契約してDocker Desktopを利用した方がよいと考えました。
理由は以下です。

Dockerまわりのセットアップやトラブルシュートが簡単であるため

Docker Desktopは、それをインストールするだけで、Dockerの利用に必要なセットアップがほとんど完了します。
また、GUIのツール上から、稼働中のコンテナやpullしたイメージを管理できるため、DockerのCUI操作に不慣れなメンバーでもトラブルシュートが比較的容易です。
実際の開発チームでは、スキルや経験が様々なメンバーが参加しているため、簡単にセットアップやトラブルシュートが可能であるというメリットは大きいと考えます。

Windowsコンテナを利用したい場合、Docker Desktopがないと厳しそうであるため

弥生の新規プロダクトの開発では、Windowsコンテナを利用して機能を実装する可能性があります。
Windows 10/11にてWindowsコンテナを利用する場合、Microsoft公式の手順では、Docker Desktopをインストールする方法が案内されています
Web上を探せば、Docker Desktopを利用せずにWindowsコンテナを利用する手順も見つかりはするのですが、多少複雑な手順となりますし、またいつまでもその手順が有効とは限りません。
前述の理由と近いですが、開発メンバーがトラブル無く開発を続けられることを重視するならば、やはり公式の手順通り、Docker DesktopをインストールしてWindowsコンテナを利用した方がよいと考えました。

契約・運用のポイント

プラン選択は"Team"プランがよさそう

2022年1月現在、Dockerの有償プランには、"Pro"、"Team"、"Business"という3つのプランがあります。
どのプランでもDocker Desktopは利用できるため、一番安い"Pro"プランを選択したくなるのですが、企業で利用する場合、"Team"プランを選択するのが現実的だと考えています。

www.docker.com

企業でソフトウェアライセンスを管理・運用する場合、「必要な分を一括で購入し、必要なメンバーに付与し、不要なメンバーからは回収する」というようなオペレーションができないと、管理が面倒すぎて運用が難しいと思います。
"Pro"プランは、個人の商用開発をターゲットとしているためか、Docker ID(=ユーザーアカウント)のそれぞれにおいて支払情報(クレカ)を紐付けて支払いを行うような設計になっているようです。
5人以下程度の組織ならばどうにか運用できるかもしれませんが、それ以上となると管理は難しいでしょう。
"Team"プランであれば、"Seats"という形でライセンスがプールされ、個別のメンバーに着脱を行うことができるため、数十人規模での運用に耐えうると思います。

f:id:ucho_yayoi:20220120201731p:plain
"Team"プランでは利用しているSeatsが表示される。Seatsの増減も可能。

”Business"プランは、SSO機能などがあるようなので、より大規模な組織での運用に適しているのではないかと思います。
ただし、"Team"プランと比較して価格が跳ね上がることと、我々としてはそこまで高度な機能を必要としていないことから、候補としてあまり検討を行いませんでした。"Business"プランは日本の代理店での取り扱いを行っているので、興味のある方はお問い合わせをしてみるとよいかもしれません。

メンバーには業務用アカウントを取得してもらう

"Team"プランでは、Organizationというグループのようなものを作成し、そこにメンバーを招待して追加していきます(追加されるとSeatsが消費されます)。
招待を行う際、Docker IDまたはメールアドレスを指定して招待を送るのですが、我々はここで社用のメールアドレス宛てに招待を送り、その社用メールアドレスを使ってDocker IDを作成してもらう運用としました。
理由は以下です。

ライセンスの利用者を明確にするため

メールアドレスを指定して招待を行うと、そのメールアドレスを紐付けたDocker IDでなければ招待元のOrganizationに参加することができないようです。
このことを利用し、招待は社用メールアドレスに対してのみ行うようにすることによって、社内の開発メンバーだけが確実に会社のOrganizationに参加するようにしました。

f:id:ucho_yayoi:20220120200954p:plain
招待されたときのDocker ID作成画面には招待を受け取ったメールアドレスを入力する欄がある

個人利用と業務利用を分けるため

個人用のDocker IDを会社のOrganizationに追加してしまうと、個人でDockerを利用している際に、誤ってOrganization内のリポジトリへの出し入れを行ってしまい、セキュリティリスクにつながる恐れがあるのではないかと考えました。
個人用と業務用のDocker IDを別にすることによって、上記のようなリスクをあらかじめ軽減できるのではないかと思います。

台帳でアカウントを管理する

せっかく社用のメールアドレスを指定して招待を行ったものの、Organizationに追加されたDocker IDに紐付いているメールアドレスを見ることはできません。見ることができるのはID文字列とプロフィールのFull Nameだけです。
そのため、「誰のIDか識別できるようにするために、ID文字列やプロフィールに本名を入れるようにしよう!」などとしたくなるのですが、ID文字列とプロフィールは公開情報となるため、本名をインターネットに公開したくないメンバーに対してそのようなことを強要するべきではないと思います…。 そこで我々は、招待したメンバーから実際に作成したID文字列を教えてもらい、それを氏名やメールアドレスと合わせてスプレッドシートで台帳管理するという、アナログな解決策を採ることにしました。
ただ、結局は退社したメンバーをOrganizationから削除するなどの棚卸し作業が必要になるため、どのみち台帳管理のようなことは必要になると思います。
(もしかしたら"Business"プランでSSOを利用すれば、認証サーバー側でIDを無効化するだけでOK、となるのかもしれませんが、詳細はわかりません…)

おわりに

Dockerの有償プランを具体的にどのように運用していくかをご紹介しました。
このような有償ライセンスは、ライセンス費用そのものに加えて、運用のコストがかかるのがつらいところです。
みなさまも、運用上の工夫ポイントなどがありましたら、ぜひ共有いただけるとうれしいです。

お知らせ

弥生では一緒に働く仲間を募集しています! herp.careers

2021年に出会った障害と2022年の目標

こんにちは、カトです。弥生でQAエンジニアをしています。

2022年、新しい年になりました。目標を立てる人も多いですね。 目標は「SMARTゴールで設定」、「モチベーションがあがる目標」が良いと言います。しかし、現状を正しく認識しないと、適切な目標を立てることはできません。 ということで、私が2021年に出会った障害をふりかえり、同じことを繰り返さないように目標を立てていきます。

障害ふりかえりに向き合ってみた話 - 弥生開発者ブログを参考に、ふりかえっていきます。

障害ふりかえりに向き合う

「カレンダーがケーキに見える」

f:id:yayoikato:20220113213045p:plain:w500
カレンダーとケーキを誤認?
安心してください。障害票のタイトルではありません。

製品・サービスの画面に、日付を指定するためのカレンダーアイコンがあります。カレンダーアイコンをクリックすることにより、カレンダーを表示し日付を選択する仕組みです。
今回の対象は、"あの"カレンダーアイコンです。

テストをしているとき、システムごとにカレンダーのアイコンが異なっていることに気がつきました。
ログを確認したところ、カレンダーアイコンを使っている1つのシステムで、カレンダーアイコンを「マンスリーカレンダー」の絵から「日めくりカレンダー」の絵に変更していました。
その変更ログに残されていたのが「カレンダーがケーキに見えるため、アイコンを変更」というメッセージでした。

なぜサービスごとにカレンダーのアイコンが異なってしまったのか、障害ふりかえりをしました。
f:id:yayoikato:20220117223359j:plain

「類似機能なのに、処理結果がちょっと違う」

f:id:yayoikato:20220113215557p:plain:w250
似ているだけではダメ?
追加機能開発において、「既存の処理と同じように」動作するように実装することがあります。
まるっきり同じ処理であれば、コードを複製するのではなく、同じ処理を呼び出すことで対応できますが、何をどの順序で呼び出すのか?流用できるところと流用できないところはどこなのか?の見極めをしなければなりません。
闇雲なコピー&ペーストでもいけないし、安易な呼び出しでもいけません。

テスト作成時、既存の処理のテストケースを見て、入力と出力が同じ結果になるようなテストパターンを検討しました。
しかし、過去に作成していた既存の処理でのテストには漏れがありました。そのテストが漏れていたパターンにおいて、既存機能と追加機能で、同じ入力をしても出力が異なってしまうという事態が発覚しました。

なぜ予定していた記述型テストで障害検出することができなかったのか、障害ふりかえりをしました。

f:id:yayoikato:20220117224945j:plain

 運用開始後、境界値が「こんにちは」

f:id:yayoikato:20220113215111p:plain:w300
境界値 隠れ身の術?
設計書に書いていない境界値があることは承知しています。「設計書に書いていないからテストしない」ではなく、「設計書に書かれていない情報を引き出して明確にする」ことが、テストの活動の一つだとも思っています。
f:id:yayoikato:20220113215122p:plain
境界値テストのイメージ
2値を選択するか、3値を選択するかという内容は、今回は割愛します。

今回の対象は、画面入力した文言に対し、内部でIDを採番してデータを持つ機能です。 IDの最小値は1。最大値は、手動でテストできない数となっていました。
最大値で登録できることの確認はコードレビュー・単体テストにて実施しました。手動テストでは、1つめの登録、2つめの登録を確認しました。
他のテストにおいても登録をしているため、テスト期間中に少なくても10回の登録は実施しています。
これで、この登録におけるテストに漏れはないと思っていました。

ところが…

f:id:yayoikato:20220113223650p:plain
突然、なにか出てきた!
しばらくすると、テスト環境で、「入力した文言ではなく、IDが表示される」という事象が発生しました。 テストをしたはずなのに、なぜ?と思いながら障害票を起票、エンジニアに調査をしてもらいました。

調査結果は、「IDを金額と同じような3桁区切りの情報として扱ってしまっている箇所があった。IDが1000以上の場合に、区切りなしの値と区切りありの値が不一致とみなされ、IDに紐づく文言ではなく、IDそのものを表示してしまっていた」ということでした。

なぜ予定していたテストで検出できなかったのか、障害ふりかえりをしました。 f:id:yayoikato:20220118073242j:plain

 ふりかえりをまとめる

「どのチームが作った」「その時、誰が担当していた」という情報は、弥生の製品・サービスを使っているお客さまにとっては関係のないことです。
チーム弥生として、お客さまには、「かんたん・あんしん・たよれる。」を提供し続けなければいけません。

ふりかえりから、2022年の目標

2021年の障害ふりかえりに向き合ってきました。
「ふりかえりは大事」であることは理解していますが、真剣に向き合うのは、大変です。

ふりかえりから、2022年の目標は、

製品・サービスの、現在を見る/過去を見る/周囲を見る


とします。

まだ、この記事の中で、私の目標は、SMARTゴールである、Specific(具体性)、Measurable(測定可能)、Achievable(達成可能)、Relevant(関連性)、Time-based(期限)は明確になっていません。
これは、また次の機会としましょう。
この目標を達成するためにやるべきことを落とし込んでいけば、SMARTゴールになっていくはずです。
目標のためにやるべきことを具体的にし、現実的に実践が可能なのかどうかを考えて、製品開発に取り組んでいきます。

さいごに

弥生の開発メンバーはどんな目標を立てているのでしょうか?
2022年最初のもくテクは、1月20日に開催です。テーマは、「新年の抱負を語ろう!LT」
さまざまな分野やキャリアのエンジニアの目標を聞いて、自分の目標をブラッシュアップしていける機会になります。
ぜひご参加ください。 mokuteku.connpass.com

弥生では、「かんたん・あんしん・たよれる。」を実現するために、一緒に、弥生の製品・サービスの品質を追求するメンバーを募集しています。
herp.careers

2021年 もくテクを再開し、月1回の開催を継続しました!

こんにちは、カトです。この記事は弥生 Advent Calendar 2021の25日目 最終日のエントリーです。

今日は12月25日。みなさんのお家にサンタクロースは来ましたか?
私は雪が降る地方の出身です。幼少期の12月25日の朝は、庭に残っているソリの跡を探すのを楽しみにしながらカーテンを開けていました。

f:id:yayoikato:20211213115601p:plain:w350

もくテク12月開催報告

2021年12月16日(木)にもくテク「AWS学習イベント DevAxのご紹介」をオンラインで開催しました。

f:id:yayoikato:20211201084148j:plain

今回のテーマ

AWS学習コンテンツ「DevAx::Academy Monoliths To Microservices」のご紹介

弥生が2021年6月~9月に実施したAWS学習イベント「DevAx::Academy Monoliths To Microservices」について。
弥生のエンジニア向けに100人規模で実施した大型の技術研修イベントの概要と、学んだことの具体例についてご紹介。

イベントの企画の話は別ブログで記載しています。こちらもご覧ください。
技術勉強会の企画を立てよう!(初心者編) - 弥生開発者ブログ

また、DevAxについて以下ブログで記載しています。こちらもご覧ください。
エンジニア100人でAWS学習コンテンツ<DevAx Academy MONOLITHS TO MICROSERVICES>を受けてみた(※日本初) - 弥生開発者ブログ

年末らしく、2021年もくテクをおさらい

f:id:yayoikato:20211220093909p:plain:w350
11月開催 2021年秋のLT大会「実践!ふりかえり ~チームで週次ふりかえりをやってみた~」資料より抜粋

ゴリラに煽られました。2021年もくテクのおさらい・ふりかえりやっていきましょう。
もくテクは2016年にはじまったイベントです。中断を経て、2021年5月にオンラインで再開し、運営メンバーも心機一転、がんばってまりました。

5月 確定申告ソフトの開発舞台裏(05/13開催)

f:id:yayoikato:20210515115847p:plain:w300:leftイベントページはこちら。関連ブログはこちら
再開にふさわしく、弥生といえば!の会計チームからの発表でした。
「会計ソフトの弥生」といわれる弥生をもってしても、要件が盛りだくさんで多忙を極めた確定申告について、会計プロジェクトのメンバーがお話ししました。

6月 新規開発における知見共有LT(06/17開催)

f:id:yayoikato:20210622201652j:plain:w300:leftイベントページはこちら。関連ブログはこちら
「会計ソフトだけじゃない弥生」による新規開発における知見の共有です。参加者からのLTを募りました。応募してくださる方はいるだろうかと運営メンバー一同、ドキドキしていました。

少人数で月1開催を続けるのは難しいだろうと判断し、社内で運営メンバー募集をして増員したのがこの時期です。

7月 もう戻りたくない!業務効率化のあれこれ(07/15開催)

f:id:yayoikato:20210715174753j:plain:w300:leftイベントページはこちら。関連ブログはこちら
もくテク最多となる94人のみなさまにご参加いただきました。ハード面、ソフト面、いろんな「業務効率化」に取り組むメンバーの発表で、いますぐ取り入れられるTipsもたくさんある会になりました。

8月 弥生TALK #リモートワーク #コミュニケーション(08/12開催)

f:id:yayoikato:20210803123532j:plain:w300:leftイベントページはこちら。関連ブログはこちら
もくテクでは、はじめてのパネルディスカッション。
「弥生の開発本部の取り組みがわかるような企画を」ということでリモートワークになっても組織・チームを意識できるような仕組みづくりをリーダーがディスカッションしました。

もくテク開催の目的の1つに弥生のエンジニア採用につなげることを意識しはじめたのがこの時期です。

9月 誰でもできる!オンライン勉強会のはじめかたLT(09/16開催)

f:id:yayoikato:20210816083206j:plain:w300:leftイベントページはこちら。関連ブログはこちら
「勉強会」で「勉強会」の話をするのはどうだろう?ということで、もくテク再開から5回目の会は、勉強会のはじめかたについて。普段は裏方の運営メンバーに、苦労や工夫・これからの意気込みを語ってもらいました。

10月 弥生で未経験の分野に挑戦したエンジニアたち(10/14開催)

f:id:yayoikato:20211214082420j:plain:w300:leftイベントページはこちら。関連ブログはこちら
弥生の「採用」を意識したテーマ会。未経験で弥生に入社して活躍するメンバー、弥生の開発本部内でキャリアチェンジしているメンバーが、それぞれのキャリアチェンジストーリーを語りました。

このもくテクの翌日10/15(金)年1度の社員総会が開始されました。もくテク運営チームが社長表彰の一つである「チームヤヨイ賞」を受賞し、また一段ともくテク運営メンバーの士気が上がりました。

社長表彰の一つである「チームヤヨイ賞」とは…
業務内・外を問わず活発に交流し、周囲に笑顔を広め明るくしたことをたたえる
または、弥生のビジョンや文化を理解・共感し、熱意を持って、主体的な行動のサポートを実施したことをたたえる
という賞です。

11月 2021年秋のLT大会(11/18開催)

f:id:yayoikato:20211116122636j:plain:w300:leftイベントページはこちら。関連ブログはこちら
「弥生開発本部の、たくさんの人・チーム・取り組みを紹介したい」を実現した会。
2021年4月新卒メンバー3人も発表しました。11月は新人のデビュー会定番になりつつある…かもしれない?

12月 AWS学習イベント DevAxのご紹介(12/16開催)

f:id:yayoikato:20211201084148j:plain:w300:leftイベントページはこちら
2021年6月~9月、開発本部全員を対象にして実施したAWS学習イベントの紹介、そして勉強会以降の学びを共有する会。
勉強会に参加して終わりではなく、それぞれのエンジニアが有効活用していることがわかる会になりました。

良い子はここまで?

何事も、華やかな現実の裏には、地味でちょっと辛い努力があるものなのです。

f:id:yayoikato:20211214074449p:plain:w300f:id:yayoikato:20211214074502p:plain:w300
サンタクロースのソリの跡にみる、理想と現実

千里の道も一歩から。日々どんな目標に向かってエンジニアが業務に向き合っているのか?を知ることができる機会になるもくテクは、2022年1月20日(木)開催です。
みなさんも新年の目標を考えながら、一緒に弥生のエンジニアの抱負を聞いてみませんか?
ぜひ、connpassイベントサイトより、参加お申込みください。

f:id:yayoikato:20211217172914j:plain

さいごに

アドベントカレンダー

弥生 Advent Calendar 2021も本日で終了です。
毎日楽しみに読んでくださったみなさま、ありがとうございました。
まだ、読めていないというみなさま、これからでも間に合います。弥生にはどんな開発者がいるのかを知ることができます。ぜひ興味のある日をクリックして、読んでみてください。

採用のお知らせ

弥生では一緒に働く仲間を募集しています! herp.careers

ソースコード検索エンジン・OpenGrokを構築しよう

この記事は 弥生 Advent Calendar 2021 の24日目の記事です。

こんにちは。弥生でエンジニアをしている、たけです。
突然ですが、この記事を読んでくださっているみなさんは、ソースコードの検索をどのように行っていますか?

普段から道に迷いやすい私ですが、ソースコードを読んでいるときにも迷子になることが多々あります。 そのうえ極度の面倒くさがりなので、「IDEを立ち上げるのもちょっとな…」と思うことがあります。

そこで、「OpenGrok」というソースコード検索エンジンを自分の開発用PCに構築することにしました。
私は普段デスクトップアプリケーションの開発を行っているのですが、Webアプリケーションの基本の勉強になりそうだと思ったことも、OpenGrokを使ってみようと思った理由の一つです。

目次

OpenGrokとは?

oracle.github.io

  • 高速のソースコード検索・相互参照エンジンです。
    • "A wicked fast source browser" (めちゃくちゃ速いソースブラウザ)です。
  • 複数のプロジェクトのソースコードを一括で検索することができます。
  • 以下のような様々な言語に対応しています。
    • C / C# / C++ / Golang / Java / JavaScript / Json / Kotlin/ Python / Ruby / Rust など

環境構築手順

公式的な環境構築手順は以下のページに記載されていますので、詳細はこちらをご参照ください。
How to setup OpenGrok · oracle/opengrok Wiki · GitHub

このブログでは、私が実際に自分の開発用PCのWindowsに構築した手順を簡単にご紹介します。

1. 事前準備

2. Ctagsをダウンロード

※Ctags:ソースファイル・ヘッダファイルの名前のインデックスファイルを生成するためのプログラム。

  • Universal Ctags をダウンロードし任意のディレクトリに展開する。
  • Path にctags.exeのパスを追加する。

3. OpenGrokの環境作成

  • OpenGrok > Download TAR Ball から「opengrok-XXX.tar.gz」をダウンロードし任意の場所に展開する。
  • OpenGrokの展開先にある、\lib\source.warを展開する。
  • 展開したsourceの配下にある、WEB-INF\web.xmlにCONFIGURATION、SRC_ROOT、DATA_ROOTを設定する。
  • sourceを、%CATALINA_HOME%(Tomcatの展開先)\webapps\にディレクトリごとコピーする。
  • %CATALINA_HOME%\conf\server.xmlの要素内に以下の行を追加する。
 <Context path="/source" docBase="source" debug="0" />

4. ソースコードを解析

  • 「3. OpenGrokの環境作成」でweb.xmlのSRC_ROOTに指定したパスに、解析したいソースコードを配置する。
  • コマンドプロンプトでOpenGrokの展開先\libに移動し以下のコマンドを実行する。
java -jar opengrok.jar -W [configuration.xmlへのパス] -c  [ctags.exeへのパス] -P -S -v -s  [ソースツリー(SRC_ROOT)へのパス] -d  [解析結果出力先(DATA_ROOT)へのパス]

5. OpenGrok を表示

  • Tomcatを起動する。(%CATALINA_HOME%\bin\startup.bat)
  • ブラウザから http://localhost:8080/source にアクセスする。
  • 以下のようなOpenGrokのトップページが表示されていれば環境構築成功です!

f:id:yayoi_ntake:20211220103905p:plain

OpenGrokでできること

  • SRC_ROOTに配置したすべてのファイルについて、以下の表の項目から検索を行うことができます。
  • 「Projects」から検索対象のプロジェクトを絞り込むことも可能です。
検索項目 検索対象
Full Search すべてのトークン
Definition シンボルの定義
Symbol シンボルの定義と参照
File Path ファイル・ディレクトリの名前
Type ファイルの種類
  • 検索結果を選択することで、ヒットした部分が含まれるファイルを開くことができます。
  • 開いたファイルの変数などをクリックすると、その定義にジャンプすることもできます。

使いどころ

上記に記載したOpenGrokの機能を使うと、

  • 複数のプロジェクトのソースコードの検索を、一括で高速に行うことが可能です。
  • 複数の条件を組み合わせた検索を簡単に行うことができます。
  • したがって、巨大なプロジェクトのソースコードを理解するのに便利です(もう迷わない)!

感想

実際にOpenGrokを使ってみて、「やはり速い!」と感じました。
私の所属するチームでは、複数の製品の開発を行っています。
そのため、「このクラス/メソッドは他にどこで使っているんだろう?」と思ったときに、複数のプロジェクトを気軽に検索することができるのはとても助かります。

また、Webアプリケーションのごく基本的な構成について、実際に環境を構築しながら学ぶ良い機会になりました。
OpenGrokを構築する環境がWindows、かつ日本語で書かれている参考情報があまり多くなく情報収集に少し苦労しましたが、それもまた良い勉強になりました。

今後やりたいこと

GitやSVNなどのバージョン管理システムとOpenGrokを連携させることで、変更履歴や差分も見られるようになるので、そちらも対応するとより便利になりそうだと思っています。

お知らせ

弥生では一緒に働く仲間を募集しています! herp.careers

マイクロサービスのAPIをRESTからGraphQLへ段階的に移行した話

こんにちは。弥生の内山です。
この記事は弥生 Advent Calendar 2021 23日目の記事です。

qiita.com

はじめに

現在、弥生では新しいサービスの開発を行っており、今後主流となりうる技術を積極的に取り入れる方針で進めています。
本記事のタイトルにあるマイクロサービスアーキテクチャやGraphQLもそのようにして取り入れてきました。
ただし、それらの技術を実際にプロダクトに適用するのは一筋縄ではいかず、いろいろな遠回りを行った末にどうにか適用できた、というのが実際のところでした。
その過程については、前回12/16のもくテクにてお話させていただきました。

mokuteku.connpass.com

この過程の中で特に苦労したのが、既にREST APIとして構築したサービス群をGraphQL APIのサービス群へ移行させることでした。
もくテクの発表では、かなりの駆け足で移行の全体をお話ししたため、このGraphQLへの移行についてあまり詳しくご説明することができませんでした。
そこで本記事では、RESTからGraphQLへ移行した過程について、少し掘り下げてご説明したいと思います。

移行前のシステム構成

移行前のシステム構成は、以下の図のようになっていました。

f:id:ucho_yayoi:20211220173234p:plain

技術構成は以下のようになっていました。

  • フロントエンド:Next.jsを使用。API RoutesにGraphQLサーバーを立ててBFFとしている。
  • バックエンド:C#(ASP.NET Core)を使用。REST APIとして各種機能をフロントエンドに提供。

この構成において、BFFは以下のような役割を持っていました。

  • フロントエンドからバックエンドのアクセスを1箇所にまとめる
  • バックエンドが提供しているREST APIを集約・変換し、GraphQL APIの形でフロントエンドへ提供する

以上の構成において特に問題となっていたのが、BFFにてREST → GraphQLへのプロトコル変換を行う処理の実装が開発スピードを落としているということでした。
そこで、この部分を見直し、今後の開発スピードを高める策を検討しました。

移行方針

GraphQLは使いたい

フロントエンドとBFFの接続にはGraphQLを使用していましたが、これはそのまま使いたいと考えました。
GraphQLのメリットは様々なところで語られていますが、クライアント側で取得するデータを決定できるという特徴が、やはりフロントエンドとの相性が良いということを実感していました。
そこで、BFFより後ろのプロトコル変換部分を見直すことにしました。

プロトコル変換は無くしたい

プロトコル変換処理を作成するのは大変ですが、APIスキーマ等から自動生成を行う等の手段によって、ある程度はその労力を削減することはできると思います。
しかし、プロトコル変換を行うレイヤーが存在すること自体が、開発のボトルネックになるのではないかと考えました。
そこで、バックエンドサービスがREST APIを提供するのをやめて、変換後のGraphQL APIを直接提供するような構成にすることにしました。

移行のための技術選定

Apollo Federation

GraphQLは、クライアント側から見えるエンドポイントを1つにするのがベストプラクティスとされています。
各バックエンドサービスがGraphQL APIを提供するのであれば、BFFの位置でそれらをまとめて1つのGraphQL APIにすることが望ましいです。

複数のGraphQL APIを束ねて1つのGraphQL APIにしたい、というときに有力な選択肢となるのが、Apollo Federation仕様です。
Apollo Federationは、Netflixが採用したことで有名になった技術で、APIを束ねるゲートウェイが各APIの関連を理解して自動的にクエリの分配・結果の統合を行ってくれます。
現時点でGraphQLのマイクロサービス構成を作るならばこれだろう、と考え、Apollo Federationを採用することにしました。

www.infoq.com

zenn.dev

Apollo Federationでは、各APIが他のAPIとどのように関連しているかをゲートウェイに示すために、独自のスキーマ拡張仕様が定義されています。
この仕様をサポートしていないとゲートウェイにぶらさがることができないため、APIの実装にはApollo Federationに対応したライブラリを使う必要があります。

C#でのGraphQL(不採用)

さて、ではC#のサーバーで実装されたREST APIを、GraphQL APIに置き換えていこうと思ったのですが、ライブラリの選定時点で頓挫してしまいました。
C#のGraphQLライブラリで最も人気があったのはgraphql-dotnetですが、以下のような理由で我々にはマッチしていないと考えました。

  • APIが難しい
    • 非常に高機能な一方で、どう書けば目的を達成できるのかを理解するのが難しかった
    • 公式のドキュメントがあまり充実しておらず、Webにも情報が少なかった
  • Federationへの対応が中途半端
    • Federation対応のAPIを書くにはSchema Firstモードを使う必要があるが、Schema Firstモードの使い方に関する情報はさらに少なく、これを調査しながら使い続けるのは現実的ではないように感じた

ちなみに、一般的にGraphQL APIを定義する方法は大きく分けてSchema First(まずスキーマを作成し、それに対応するリゾルバを実装する)とCode First(クラス定義等からスキーマが生成される)があり、世の中の多くのライブラリはSchema Firstを採用しています。
どちらの方法も一長一短ですが、API実装者がAPI定義も行う場合は、Code Firstの方がスキーマ定義と実装との不一致が起こらないため、有効だと感じます。
なお、graphql-dotnetはSchema FirstとCode Firstの両方をサポートしているライブラリです。

また、graphql-dotnet以外には実用レベルに至っていると感じられるライブラリが見つけられませんでした。
このため、C#でFederation対応のGraphQL APIを実装することは困難であると考えました。

NestJS + GraphQL

C#での実装が難しいということがわかったため、他の選択肢を検討しました。
GraphQLのサポートが強力なのはやはりJavaScript/TypeScriptベースのライブラリでした。
その中でもNestJSは、Code FirstモードでFederation対応のAPI定義をサポートしているため、我々の要求にピッタリ合うという印象でした。

docs.nestjs.com

また、NestJSを採用すれば、フロントエンドもバックエンドもTypeScriptで開発できるようになるため、1つの機能を開発する際のオーバーヘッドが削減できそうです。
以上のことから、バックエンドの各サービスはNestJSを用いて開発することにしました。

お試し移行

しかし、既にC# + RESTで開発したAPI実装を、NestJS + GraphQLのAPIに変更するということは、つまりバックエンドサービス群を新しい技術スタックでまるごと書き直すということになります。
さすがにそれをいきなり実行するのはリスクが高すぎるため、まずは新規機能のために開発するAPIサーバーを、この新しい技術スタックで作成してみることにしました。

作成してみて、これまでの技術スタック(C# + REST、BFF内でGraphQLへ変換)で開発していたときと比較し、機能が完成するまでのスピードが明らかに早くなったと感じました。
単純に記述するコードの量が減りましたし、言語やプロトコルを頭の中で切り替える必要がなくなったので、作業効率もアップしたのだと思います。
この新しいGraphQL APIの実装方法に手応えを感じたため、これまでに作成してきた機能についても、新しい技術スタックへの置き換えを進めることにしました。

APIのマージ

さて、新しくGraphQL APIを立てたものの、このAPIを既存のシステムにうまく接合することができていませんでした。
この新しいAPIもBFFにぶらさげる形としたかったのですが、以下のような理由によりそれができませんでした。

  • Apollo ServerはREST API等の複数のデータソースを変換して1つのGraphQL APIにまとめることはできるが、GraphQLのデータソースはサポートしていなさそう
  • Apollo Gatewayは、複数のGraphQL APIをまとめることはできるが、GraphQL以外のAPIをまとめることはできなさそう

そのため、実は新しいAPIはフロントエンドから旧APIと別に呼んで、フロントエンドで結果をマージするという、かなり乱暴な暫定処置を行っていたのでした。
(新しいAPIとこれまでのAPIがそれほど結びつきが強くないということも幸いし、この処置でどうにかなったのでした)

しかし、このままではフロントエンドが複数のAPIエンドポイントを呼ぶ形になってしまい、複雑さが高くなってしまうのは明白です。
また、これまで作成したREST API群をGraphQL APIに置き換えていくときに、全てのAPIを一気にGraphQLにするのではなく、APIサーバーを順番にGraphQLに書き直してシステムに接合していけるような方法が採れないと、移行のリスクが高くなってしまうと考えました。
そこで思いついたのが、「REST APIをまとめてGraphQL APIにするサーバー」と、「各GraphQL APIをまとめるサーバー」の2段構成にするアイデアでした。

移行ステップ

以下のようなステップを経て、REST API群をGraphQL APIへ置き換えていきました。

1. REST APIを集約する部分を切り出す

今まではNext.js上のAPI RoutesにApollo Serverを配置し、これがREST APIを集約してGraphQL APIを提供していました。
このApollo ServerをBFFから切り離し、独立したサービス(API Gateway)として動作させるようにしました。

f:id:ucho_yayoi:20211220173237p:plain

2. GraphQLをまとめる

システム上に、2つのGraphQL APIサーバー(API Gatewayと、新規機能開発で作成したGraphQL APIサーバー)が存在する状態になるので、これらをApollo Gatewayを使って集約し、1つのGraphQL APIにします。
Apollo Gatewayは、いったんAPI Routesに配置します。
これによって、フロントエンド側からは1つのGraphQL APIだけが見える状態になります。
(新APIがフロントエンドに直結されてしまう問題もこれで解決できます)

f:id:ucho_yayoi:20211220173239p:plain

3. REST APIサービスをGraphQL APIサービスに移行する

この状態であれば、REST APIサーバーの1つをGraphQL APIサーバーに書き直しても、API RoutesのApollo Gatewayの下にぶらさげれば、フロントエンドから見たGraphQL APIとしては変化しないということになります。
これによって、REST APIサーバーをひとつずつGraphQL APIサーバーに書き直して、順次システムに接合する、ということが可能になります。

f:id:ucho_yayoi:20211220173242p:plain

4. API Gatewayを切り出す

REST APIサーバーをすべてGraphQL APIサーバーに書き直した後は、REST APIを集約していたApollo Serverが必要なくなります。
また、各Next.jsアプリのAPI Routesに置いたApollo Gatewayがほとんど同じことをやっているため、これらを1つにまとめたいです。
そこで、API GatewayにApollo Gateway(名前が紛らわしいですね)を配置するようにします。
ここまで実施すれば、GraphQLなマイクロサービス構成への移行が完了です。

f:id:ucho_yayoi:20211220173231p:plain

まとめ

こうして振り返ってみると、なんだか非常に遠回りをしたような気がします…。
しかし、結果としてすっきりした技術構成へ移行することができましたし、移行過程でGraphQLまわりに関する知見を深めることができたと思います。
この記事が、GraphQLへの移行を試みる方の参考になればうれしいです。

お知らせ

弥生では一緒に働く仲間を募集しています! herp.careers