実践！Swift API Design Guidelines に基づいた簡潔明瞭な API の作り方

Product Engineer 西 悠作 @jrsaruo_tech

後夜祭 iOSDC Japan 2023 登壇資料

コードを読みやすく・挙動を予測しやすくするために、 Swift の API Design Guidelines を活用しましょう。

本トークでは実際のコード例をもとに

- ガイドラインの示す API の理想像とは？
- API 設計における大事な観点とは？

を解説します。
API の構成要素すべてを洗練させ、簡潔明瞭で美しいAPIをデザインしましょう！

Transcript

1. $PQZSJHIU
   ˜
   
   1SFTFOU
   "/%1"%
   *OD
   5IJT
   JOGPSNBUJPO
   JT
   DPOGJEFOUJBM
   BOE
   XBT
   QSFQBSFE
   CZ
   "/%1"%
   *OD
   GPS
   UIF
   VTF
   PG
   PVS
   DMJFOU
   *U
   JT
   OPU
   UP
   CF
   SFMJFE
   PO
   CZ
   BOE
   SE
   QBSUZ
   
   
   1SPQSJFUBSZ
   
   $POGJEFOUJBM
   
   
   
   ແஅసࡌɾແஅෳ੡ͷېࢭ ࣮ફʂSwift API Design Guidelinesʹج͍ͮͨ ؆ܿ໌ྎͳAPIͷ࡞Γํ ੢ ༔࡞
2. ੢ ༔࡞ @jrsaruo_tech ΞχϝɹອըɹήʔϜɹSwift 1996೥12݄21೔ੜ גࣜձࣾΞϯυύου େࡕग़਎ ੢ ஀ੜ ੢ ੒௕ 
3. SwiftͷAPI Design Guidelinesͱ͸ APIɿApplication Programming Interface Swiftʹ͓͚Δʰྑ͍APIʱͷ࡞ΓํΛࣔͨ͠΋ͷ ϝιου΍ϓϩύςΟͱ͍ͬͨΠϯλʔϑΣΠε  https://www.swift.org/documentation/api-design-guidelines/
4. API Design Guidelinesͷࣔ͢ʰྑ͍APIʱͱ͸ʁͦΕΛ࡞Δʹ͸ʁ ຊ೔࿩͢͜ͱ ͜Μͳ࿩΋͔ͨͬͨ͠Ͱ͕͢ຊ೔͸ׂѪɿ move(destination:)ΑΓ΋move(to:)ʂ bookId͡Όͳͯ͘bookIDʂ shopUrl͡Όͳͯ͘shopURLʂ 
5.  let string = input.message.trim() let mail = try await Mailer.sendMail(string, to: "Taro") mailBox.update(mail: mail, bottom: false) ԿΛτϦϛϯά͍ͯ͠Δʁ
   input.messageࣗମΛՃ޻͍ͯ͠Δʁ ԿΛ͍ͯ͠Δʁ bottom: falseͱ͸ʁ
   trueʹ͢ΔͱͲ͏ͳΔʁ ϝʔϧΞυϨεͰ͸ͳ͘ਓ໊ʁ 🤔
6. let message = input.message.trimmingWhitespaces() let sentMail = try await Mailer.send(message, toAddress: "Taro") mailBox.insert(sentMail, at: .top)  🙂 Ҿ਺ؒҧ͑ͯΔʂ
7. એݴଆҎ্ʹར༻ଆͰͷ໌շ͕͞࠷ॏཁ API Design Guidelines - Fundamentals ؆ܿ͞ΑΓ΋໌շ͞ͷํ͕େࣄ ϝιου΍ϓϩύςΟͷએݴ͸1Օॴ͕ͩར༻͸ෳ਺Օॴ ؆ܿ͞͸SwiftͷݴޠػೳʹΑΔ෭࣍ޮՌɻΰʔϧͰ͸ͳ͍  υΩϡϝϯτίϝϯτ΋ॻ͜͏Ͷ
8. ໌շͱ͸ʁ
9. ڍಈΛ༧ଌ͠΍͍͢ ໌շͳAPIͱ͸ ࢖͍ؒҧ͑ʹ͍͘ɺؒҧͬͨ࢖͍ํ͕Ͱ͖ͳ͍ ʮݺͿͱԿ͕ى͖Δͷ͔ʯ͕͸͖ͬΓ෼͔Δ ࢖͍ํ͕෼͔Γ΍͍͢ 
10. ৘ใΛෆ଍ͤ͞ͳ͍ ໌շͳAPIΛઃܭ͢Δʹ͸ ৘ใΛ๞࿨ͤ͞ͳ͍ ৘ใ͕ଟ͗͢Δͱೝ஌ෛՙ্͕͕Δ ৘ใ͕গͳ͗͢ΔͱᐆດʹͳΔ 
11. ৑௕͞͸ͳ͍͔ʁ APIͷ໾ׂ͸ʁ ໌շͳAPIΛઃܭ͢ΔͨΊͷ4ͭͷ໰͍ ৘ใ͸଍Γ͍ͯΔ͔ʁ ෭࡞༻͸͋Δ͔ʁࣗ਎Λมߋ͢Δ͔ʁ 
12.  let mail = try await Mailer.sendMail(string, to: "...") mailBox.update(mail: mail, bottom: false) let string = input.message.trim()
13. let string = input.message.trim() func trim() -> String  Q. APIͷ໾ׂ͸ʁ Q. ࣗ਎Λมߋ͢Δ͔ʁ ༨നΛτϦϛϯάͨ͠จࣈྻΛฦ͢ Q. ৑௕͞͸ͳ͍͔ʁ Q. ৘ใ͸଍Γ͍ͯΔ͔ʁ
14. let string = input.message.trimWhitespaces() func trimWhitespaces() -> String  Q. APIͷ໾ׂ͸ʁ Q. ࣗ਎Λมߋ͢Δ͔ʁ ༨നΛτϦϛϯάͨ͠จࣈྻΛฦ͢ ͠ͳ͍ Q. ৑௕͞͸ͳ͍͔ʁ Q. ৘ใ͸଍Γ͍ͯΔ͔ʁ FEɺJOHܗʹ͢Δ
15.  let string = input.message.trimmingWhitespaces() func trimmingWhitespaces() -> String Q. APIͷ໾ׂ͸ʁ Q. ࣗ਎Λมߋ͢Δ͔ʁ ͠ͳ͍ Q. ৑௕͞͸ͳ͍͔ʁ 0, Q. ৘ใ͸଍Γ͍ͯΔ͔ʁ 0, FEɺJOHܗʹ͢Δ ༨നΛτϦϛϯάͨ͠จࣈྻΛฦ͢
16.  let mail = try await Mailer.sendMail(string, to: "...") mailBox.update(mail: mail, bottom: false) let string = input.message.trimmingWhitespaces()
17.  let mail = try await Mailer.sendMail(string, to: "...") func sendMail( _ message: String, to destinationAddress: String ) async throws -> Mail Q. APIͷ໾ׂ͸ʁ Q. ෭࡞༻͸͋Δ͔ʁ ࢦఆͷѼઌʹϝʔϧΛૹ৴͢Δ ͋Δ Q. ৑௕͞͸ͳ͍͔ʁ Q. ৘ใ͸଍Γ͍ͯΔ͔ʁ to͚ͩͰ͸ͲΜͳจࣈྻͳͷ͔ར༻ଆͰ෼͔Γʹ͍͘ ໋ྩܗʹ͢Δ ܕ৘ใ͕ऑ͍ͱى͖͕ͪ Any, Int, String, ...
18.  func sendMail( _ message: String, toAddress destinationAddress: String ) async throws -> Mail Q. APIͷ໾ׂ͸ʁ Q. ෭࡞༻͸͋Δ͔ʁ ࢦఆͷѼઌʹϝʔϧΛૹ৴͢Δ ͋Δ Q. ৑௕͞͸ͳ͍͔ʁ Mail͸ແͯ͘΋఻ΘΔʢMailer͔ΒਪଌͰ͖Δʣ Q. ৘ใ͸଍Γ͍ͯΔ͔ʁ let mail = try await Mailer.sendMail(string, toAddress: "...") ໋ྩܗʹ͢Δ ܕ৘ใ͕ऑ͍ͱى͖͕ͪ Any, Int, String, ... to͚ͩͰ͸ͲΜͳจࣈྻͳͷ͔ར༻ଆͰ෼͔Γʹ͍͘
19.  func send( _ message: String, toAddress destinationAddress: String ) async throws -> Mail Q. APIͷ໾ׂ͸ʁ Q. ෭࡞༻͸͋Δ͔ʁ ࢦఆͷѼઌʹϝʔϧΛૹ৴͢Δ ͋Δ Q. ৑௕͞͸ͳ͍͔ʁ Mail͸ແͯ͘΋఻ΘΔʢMailer͔ΒਪଌͰ͖Δʣ Q. ৘ใ͸଍Γ͍ͯΔ͔ʁ let mail = try await Mailer.send(string, toAddress: "...") ໋ྩܗʹ͢Δ ܕ৘ใ͕ऑ͍ͱى͖͕ͪ Any, Int, String, ... to͚ͩͰ͸ͲΜͳจࣈྻͳͷ͔ར༻ଆͰ෼͔Γʹ͍͘
20.  let string = input.message.trimmingWhitespaces() mailBox.update(mail: mail, bottom: false) let mail = try await Mailer.send(string, toAddress: "...")
21.  func update(mail: Mail, bottom: Bool) Q. APIͷ໾ׂ͸ʁ Q. ࣗ਎Λมߋ͢Δ͔ʁ ϝʔϧΛϝʔϧϘοΫεͷτοϓʹૠೖ͢Δ Q. ৑௕͞͸ͳ͍͔ʁ Q. ৘ใ͸଍Γ͍ͯΔ͔ʁ mailBox.update(mail: mail, bottom: false)
22.  func insert(mail: Mail, bottom: Bool) Q. APIͷ໾ׂ͸ʁ Q. ࣗ਎Λมߋ͢Δ͔ʁ ϝʔϧΛϝʔϧϘοΫεͷτοϓʹૠೖ͢Δ Q. ৑௕͞͸ͳ͍͔ʁ Q. ৘ใ͸଍Γ͍ͯΔ͔ʁ mailBox.insert(mail: mail, bottom: false) ໨తޠ
23.  func insertMail(_ mail: Mail, bottom: Bool) Q. APIͷ໾ׂ͸ʁ Q. ࣗ਎Λมߋ͢Δ͔ʁ ϝʔϧΛϝʔϧϘοΫεͷτοϓʹૠೖ͢Δ ͢Δ Q. ৑௕͞͸ͳ͍͔ʁ Q. ৘ใ͸଍Γ͍ͯΔ͔ʁ bottom: false͸ᐆດ mailBox.insertMail(mail, bottom: false) ໋ྩܗʹ͢Δ enumʹͯ͠ΈΔ
24.  func insertMail(_ mail: Mail, at position: InsertPosition) Q. APIͷ໾ׂ͸ʁ Q. ࣗ਎Λมߋ͢Δ͔ʁ ϝʔϧΛϝʔϧϘοΫεͷτοϓʹૠೖ͢Δ ͢Δ Q. ৑௕͞͸ͳ͍͔ʁ Q. ৘ใ͸଍Γ͍ͯΔ͔ʁ Mail͸ແͯ͘΋఻ΘΔ bottom: false͸ᐆດ mailBox.insertMail(mail, at: .top) ໋ྩܗʹ͢Δ enumʹͯ͠ΈΔ
25.  func insert(_ mail: Mail, at position: InsertPosition) Q. APIͷ໾ׂ͸ʁ Q. ࣗ਎Λมߋ͢Δ͔ʁ ϝʔϧΛϝʔϧϘοΫεͷτοϓʹૠೖ͢Δ ͢Δ Q. ৑௕͞͸ͳ͍͔ʁ Q. ৘ใ͸଍Γ͍ͯΔ͔ʁ Mail͸ແͯ͘΋఻ΘΔ bottom: false͸ᐆດ mailBox.insert(mail, at: .top) ໋ྩܗʹ͢Δ enumʹͯ͠ΈΔ
26.  string = input.message.trimmingWhitespaces() string, toAddress: "...") mail = try await Mailer.send( let let mailBox.insert(mail, at: .top)
27.  message = input.message.trimmingWhitespaces() message, toAddress: "...") mail = try await Mailer.send( let let mailBox.insert(mail, at: .top) mailBox.insert(mail, at: .top)
28.  sentMail = try await Mailer.send(message, toAddress: "...") message = input.message.trimmingWhitespaces() let let mailBox.insert(sentMail, at: .top)
29.  sentMail = try await Mailer.send(message, toAddress: "...") message = input.message.trimmingWhitespaces() let let let string = input.message.trimString() let mail = try await Mailer.sendMail(string, to: "...") mailBox.update(mail: mail, bottom: false) 🤔 🙂 mailBox.insert(sentMail, at: .top)
30. API Design GuidelinesΛಡ΋͏ ར༻ଆͰͷ໌շ͞Λॏࢹ͠Α͏ ·ͱΊ ໌շͳAPIΛઃܭ͢ΔͨΊͷ4ͭͷ໰͍ APIͷ໾ׂɺ෭࡞༻͸͋Δ͔ɺ৘ใ͸଍Γ͍ͯΔ͔ɺ৑௕͞͸ͳ͍͔ 
31. We are Hiring !!  IUUQTFOHJOFFSBOEQBEDPKQ ΤϯδχΞ࠾༻
32.  ͋Γ͕ͱ͏͍͟͝·ͨ͠ @jrsaruo_tech 'PMMPX
    NF 𝕏