API仕様書から自前でコード生成して運用した話 / DroidKaigi 2018 Reject Conference

DroidKaigi 2018 の Reject Conference での発表資料です。

Transcript

1. API仕様書から⾃前でコー ド⽣成して運⽤した話 Tunnel 株式会社 鷲⽥ 基 
2. ⾃⼰紹介 
3. ⾃⼰紹介 名前: 鷲⽥ 基 Twitter: @wm3 DroidKaigi スタッフ (Webサイト, 司会) RoomClip アプリエンジニア 
4. インテリア写真を共有する CGM 
5. DroidKaigi のスポンサーとして参加しました 
6. 
7. 皆さんに質問 
8. API の仕様の管理どう やっていますか? 
9. Swagger 
10. Protocol Buffers 
11. GraphQL 
12. 真のプログラマに
 仕様書は必要ない 
13. ⾃前でコード⽣成
 ツールを作る 
14. 
15. RoomClip の場合 
16. まともな仕様書は無い 
17. 真のプログラマ集団 
18. 
19. 実際は⼀貫性のない API実装でボロボロ 
20. ⼀貫性のないレスポンス 何もない値として null と空⽂字が存在  [ { "url": "http://example.com" }, { "url": null }, // url ͸ແ͍ { "url": "" }, // url ͸ແ͍(?) ] ※ 実際のレスポンスとは異なります
21. ⼀貫性のないレスポンス 0 や "0" を真偽値のように扱う  { "success": "0" } { "success": 0 } ※ 実際のレスポンスとは異なります
22. ⼀貫性のないレスポンス どっちを使えば良いのかわからない  { "image_url": "…", "real_image_url": "…", } ※ 実際のレスポンスとは異なります
23. 
24. API仕様を管理したい 
25. 実は昔 API 仕様書を作っていた しかし途中で破綻 API 仕様書とコードの同期が負担 仮に最⾼品質の仕様書を⽤意しても解決しなそう API を管理したい 
26. コード⽣成に注⼒する のが正解では? 
27. → API コードを⾃動⽣成する → API の品質の安定化を図る ⽬標とした事 
28. ＿⼈⼈⼈⼈⼈⼈⼈⼈⼈⼈⼈⼈⼈⼈⼈⼈＿ ＞ ⾃前でコード⽣成ツールを作る ＜ ￣Y^Y^Y^Y^Y^Y^Y^Y^Y^Y^Y^Y^Y^Y^Y￣ 
29. どんなツール? 
30. ⼊⼒: YAML で書かれた仕様書 出⼒: Android, iOS, PHP 変換⽅法: Mustache + TypeScript ⾃前コード⽣成ツールの概要 
31. 例: 写真検索 API 
32. 写真検索 API の例  IUUQFYBNQMFDPNQIPUPT RΩονϯQBHF { "photos": [ { "id": 111, "url": "http://example.com/111.jpg" }, { "id": 222, "url": "http://example.com/222.jpg" }, ... ], "total_count": 123 }
33. YAML の定義  --- !api name: GetPhotoList request: GET /photos description: ࣸਅҰཡΛड͚औΔɻ param: - q: String - page: Integer? response: - photos: GetPhotoList.Photo[]* - total_count: Integer nested: - !class name: Photo properties: - id: Integer - url: String
34. YAML の定義  --- !api name: GetPhotoList request: GET /photos description: ࣸਅҰཡΛड͚औΔɻ param: - q: String - page: Integer? response: - photos: GetPhotoList.Photo[]* - total_count: Integer nested: - !class name: Photo properties: - id: Integer - url: String
35. YAML の定義  --- !api name: GetPhotoList request: GET /photos description: ࣸਅҰཡΛड͚औΔɻ param: - q: String - page: Integer? response: - photos: GetPhotoList.Photo[]* - total_count: Integer nested: - !class name: Photo properties: - id: Integer - url: String
36. 出⼒例(Java) ※ 実際はもっと複雑なコードができます  /** * <p>ࣸਅҰཡΛड͚औΔɻ</p> */ @SuppressWarnings({ "unused", "WeakerAccess" }) public final class GetPhotoList { public static final String method = "GET"; public static final String url = "/photos"; public static final class Param<R> extends AbstractBuilder<R> { public Param(……) { …… } @Nonnull public GetPhotoList.Param<R> q(@Nonnull String value) { …… } @Nonnull public GetPhotoList.Param<R> page(@Nullable Integer value) { …… } } public static final class Response extends AbstractComposite { @Nullable public final List<GetPhotoList.Photo> photos; public final int totalCount; @Keep public Response(@Nonnull AttributeMap map) { …… } } public static final class Photo extends AbstractComposite { public final int id; @Nonnull public final String url; @Keep public Photo(@Nonnull AttributeMap map) { …… } } }
37. 出⼒例(Java) ※ 実際はもっと複雑なコードができます  /** * <p>ࣸਅҰཡΛड͚औΔɻ</p> */ @SuppressWarnings({ "unused", "WeakerAccess" }) public final class GetPhotoList { public static final String method = "GET"; public static final String url = "/photos"; public static final class Param<R> extends AbstractBuilder<R> { public Param(……) { …… } @Nonnull public GetPhotoList.Param<R> q(@Nonnull String value) { …… } @Nonnull public GetPhotoList.Param<R> page(@Nullable Integer value) { …… } } public static final class Response extends AbstractComposite { @Nullable public final List<GetPhotoList.Photo> photos; public final int totalCount; @Keep public Response(@Nonnull AttributeMap map) { …… } } public static final class Photo extends AbstractComposite { public final int id; @Nonnull public final String url; @Keep public Photo(@Nonnull AttributeMap map) { …… } } }
38. 出⼒例(Java) ※ 実際はもっと複雑なコードができます  /** * <p>ࣸਅҰཡΛड͚औΔɻ</p> */ @SuppressWarnings({ "unused", "WeakerAccess" }) public final class GetPhotoList { public static final String method = "GET"; public static final String url = "/photos"; public static final class Param<R> extends AbstractBuilder<R> { public Param(……) { …… } @Nonnull public GetPhotoList.Param<R> q(@Nonnull String value) { …… } @Nonnull public GetPhotoList.Param<R> page(@Nullable Integer value) { …… } } public static final class Response extends AbstractComposite { @Nullable public final List<GetPhotoList.Photo> photos; public final int totalCount; @Keep public Response(@Nonnull AttributeMap map) { …… } } public static final class Photo extends AbstractComposite { public final int id; @Nonnull public final String url; @Keep public Photo(@Nonnull AttributeMap map) { …… } } }
39. 出⼒例(PHPおよびSwift)  <?php namespace API_Reference; /** * GetPhotoList * * ࣸਅҰཡΛड͚औΔɻ * * @package com.tunnel.roomclip.generated * @module items */ /** * Param * * @type AbstractForm */ class GetPhotoListParam extends API_Request { public $q = 'API_Reference\API_String'; public $page = 'API_Reference\API_Integer'; } /** * Response * * @type AbstractComposite */ class GetPhotoListResponse extends API_Object { protected $isOptional = []; protected $isEmptyAllowed = ["photos"]; public $photos = 'API_Reference\List<GetPhotoListPhoto>'; public $total_count = 'API_Reference\API_Integer'; } /** * Photo * * @type AbstractComposite */ class GetPhotoListPhoto extends API_Object { protected $isOptional = []; protected $isEmptyAllowed = []; public $id = 'API_Reference\API_Integer'; public $url = 'API_Reference\API_String'; } /// /// ࣸਅҰཡΛड͚औΔɻ /// struct GetPhotoList { static let method = ApiMethod.get static let url = "/photos" struct Param: BuilderValue { var q: String var page: Int? init( q: String, page: Int? = nil ) { self.q = q self.page = page } var apiRequestParamDictionary: [String: ApiRequestParam] { var values = [String: ApiRequestParam]() values["q"] = q.apiRequestParam if let v = page { values["page"] = v.apiRequestParam } return values } } struct Response: CompositeValue { var photos: [GetPhotoList.Photo]? var totalCount: Int init(children: MapResponseDecodable) throws { self.photos = try children.decode("photos", into: GetPhotoList.Photo.listAllowingEmpty()) self.totalCount = try children.decode("total_count", into: Int.singleRequired()) } } struct Photo: CompositeValue { var id: Int var url: String init(children: MapResponseDecodable) throws { self.id = try children.decode("id", into: Int.singleRequired()) self.url = try children.decode("url", into: String.singleRequired()) } } }
40. 
41. なぜ⾃前でツール 作っちゃったの? 
42. 既存の API でも適⽤できる ⾏儀の悪い既存 API にも柔軟に対応したい 記述の簡潔さ 「良い設計」=「書きやすい設計」にしたい 捨てられビリティ 選択を失敗した場合は撤退・移⾏できる 重要視した事 
43. 既存の API でも適⽤できる ⾏儀の悪い既存 API にも柔軟に対応したい → GraphQL や Protocol Buffers は対象外 記述の簡潔さ 「良い設計」=「書きやすい設計」にしたい → 仕様書の仕様を⾃由に作れる (あと Swagger 書くの⾟そう) 捨てられビリティ 選択を失敗した場合は撤退・移⾏できる → 他のツールの仕様書に変換(コード⽣成)可能 重要視した事  ※ 選定したのは 2016 年後半
44. 最⾼のAPI設計を簡単 にかけるツールを作り 上げるぞ！ 
45. 
46. API品質向上のために ⼯夫した事 
47. 1. 必須属性とオプショ ナル属性 
48. デフォルトで必須属性 不⽤意にオプショナルにさせない 「?」をつけるとオプショナル Kotlin などでもおなじみ 必須属性とオプショナル属性 
49. 必須属性とオプショナル属性  # ΞΧ΢ϯτ৘ใ response: - fullname: String # required - twitter: String? # optional
50. 必須属性とオプショナル属性  { "fullname": "࿯ా ج", "twitter": "@wm3" } # ΞΧ΢ϯτ৘ใ response: - fullname: String # required - twitter: String? # optional
51. 必須属性とオプショナル属性  { "fullname": "࿯ా ج", "twitter": null } # ΞΧ΢ϯτ৘ใ response: - fullname: String # required - twitter: String? # optional
52. 必須属性とオプショナル属性  { "fullname": null, ɹ "twitter": "@wm3" } # ΞΧ΢ϯτ৘ใ response: - fullname: String # required - twitter: String? # optional
53. 2. 空許容属性 
54. 属性値に「空の値を許容するか」を指定 Stringおよび配列で指定可能 デフォルトで空の値を許可しない null 的な意味で扱われる事が多いため 型に「*」をつけると空の値を許容 正規表現のイメージ 「*」と「?」を組み合わせる事も可能 ⾮推奨。主に既存 API の互換性のため 空許容属性 
55. 必須属性とオプショナル属性  # ΞΧ΢ϯτ৘ใ response: - fullname: String # required - twitter: String* # empty allowed
56. 必須属性とオプショナル属性  { "fullname": "",ɹɹɹ "twitter": "@wm3" } # ΞΧ΢ϯτ৘ใ response: - fullname: String # required - twitter: String* # empty allowed
57. 必須属性とオプショナル属性  { "fullname": "࿯ా ج", "twitter": "" } # ΞΧ΢ϯτ৘ใ response: - fullname: String # required - twitter: String* # empty allowed
58. 必須属性とオプショナル属性  { "fullname": "࿯ా ج", "twitter": null } # ΞΧ΢ϯτ৘ใ response: - fullname: String # required - twitter: String* # empty allowed
59. その他の⼯夫 • ID 型 • DateStr 型 • ちょっと時間ない… 
60. 実装 
61. ドキュメント⽣成ツール作成開始 ⼀週間後、YamlからHTMLを⽣成可能に APIを仕様書に落とす運⽤を開始 新規および既存のAPI API仕様のガイドラインを作成 URL形式やレスポンス形式のルールなど 実装開始 (2016年9⽉頃) 
62. コード⽣成開始は
 もうちょっと後 
63. 2016年11⽉ Android ⽤コードを⽣成 2017年3⽉ サーバー⽤コードを⽣成 2017年4⽉ iOS⽤コードを⽣成 コード⽣成の実装(2016年末〜2017年前半)  ※ 他のタスクもやりながらの作業
64. まとめ 
65. まとめ • API仕様の管理⽅法として、コード⽣ 成ツールを⾃作するという選択をした • コード⽣成は現実的な⼿段。考慮して も良いのでは? 
66. …と思っているのです が、少数派な気もする 
67. 何かあったらぜひ声を かけてください！ 
68. 
69. ΤϯδχΞืूத ͓ؾܰʹ࿈བྷ͍ͩ͘͞ʂ