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

Slide 1

Slide 1 text

$PQZSJHIU1SFTFOU"/%1"%*OD5IJTJOGPSNBUJPOJTDPOGJEFOUJBMBOEXBTQSFQBSFECZ"/%1"%*ODGPSUIFVTFPGPVSDMJFOU*UJTOPUUPCFSFMJFEPOCZBOESEQBSUZ1SPQSJFUBSZ$POGJEFOUJBMແஅసࡌɾແஅෳ੡ͷېࢭ ࣮ફʂSwift API Design Guidelinesʹج͍ͮͨ ؆ܿ໌ྎͳAPIͷ࡞Γํ ੢ ༔࡞

Slide 2

Slide 2 text

੢ ༔࡞ @jrsaruo_tech ΞχϝɹອըɹήʔϜɹSwift 1996೥12݄21೔ੜ גࣜձࣾΞϯυύου େࡕग़਎ ੢ ஀ੜ ੢ ੒௕

Slide 3

Slide 3 text

SwiftͷAPI Design Guidelinesͱ͸ APIɿApplication Programming Interface Swiftʹ͓͚Δʰྑ͍APIʱͷ࡞ΓํΛࣔͨ͠΋ͷ ϝιου΍ϓϩύςΟͱ͍ͬͨΠϯλʔϑΣΠε https://www.swift.org/documentation/api-design-guidelines/

Slide 4

Slide 4 text

API Design Guidelinesͷࣔ͢ʰྑ͍APIʱͱ͸ʁͦΕΛ࡞Δʹ͸ʁ ຊ೔࿩͢͜ͱ ͜Μͳ࿩΋͔ͨͬͨ͠Ͱ͕͢ຊ೔͸ׂѪɿ move(destination:)ΑΓ΋move(to:)ʂ bookId͡Όͳͯ͘bookIDʂ shopUrl͡Όͳͯ͘shopURLʂ

Slide 5

Slide 5 text

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ʹ͢ΔͱͲ͏ͳΔʁ ϝʔϧΞυϨεͰ͸ͳ͘ਓ໊ʁ 🤔

Slide 6

Slide 6 text

let message = input.message.trimmingWhitespaces() let sentMail = try await Mailer.send(message, toAddress: "Taro") mailBox.insert(sentMail, at: .top) 🙂 Ҿ਺ؒҧ͑ͯΔʂ

Slide 7

Slide 7 text

એݴଆҎ্ʹར༻ଆͰͷ໌շ͕͞࠷ॏཁ API Design Guidelines - Fundamentals ؆ܿ͞ΑΓ΋໌շ͞ͷํ͕େࣄ ϝιου΍ϓϩύςΟͷએݴ͸1Օॴ͕ͩར༻͸ෳ਺Օॴ ؆ܿ͞͸SwiftͷݴޠػೳʹΑΔ෭࣍ޮՌɻΰʔϧͰ͸ͳ͍ υΩϡϝϯτίϝϯτ΋ॻ͜͏Ͷ

Slide 8

Slide 8 text

໌շͱ͸ʁ

Slide 9

Slide 9 text

ڍಈΛ༧ଌ͠΍͍͢ ໌շͳAPIͱ͸ ࢖͍ؒҧ͑ʹ͍͘ɺؒҧͬͨ࢖͍ํ͕Ͱ͖ͳ͍ ʮݺͿͱԿ͕ى͖Δͷ͔ʯ͕͸͖ͬΓ෼͔Δ ࢖͍ํ͕෼͔Γ΍͍͢

Slide 10

Slide 10 text

৘ใΛෆ଍ͤ͞ͳ͍ ໌շͳAPIΛઃܭ͢Δʹ͸ ৘ใΛ๞࿨ͤ͞ͳ͍ ৘ใ͕ଟ͗͢Δͱೝ஌ෛՙ্͕͕Δ ৘ใ͕গͳ͗͢ΔͱᐆດʹͳΔ

Slide 11

Slide 11 text

৑௕͞͸ͳ͍͔ʁ APIͷ໾ׂ͸ʁ ໌շͳAPIΛઃܭ͢ΔͨΊͷ4ͭͷ໰͍ ৘ใ͸଍Γ͍ͯΔ͔ʁ ෭࡞༻͸͋Δ͔ʁࣗ਎Λมߋ͢Δ͔ʁ

Slide 12

Slide 12 text

let mail = try await Mailer.sendMail(string, to: "...") mailBox.update(mail: mail, bottom: false) let string = input.message.trim()

Slide 13

Slide 13 text

let string = input.message.trim() func trim() -> String Q. APIͷ໾ׂ͸ʁ Q. ࣗ਎Λมߋ͢Δ͔ʁ ༨നΛτϦϛϯάͨ͠จࣈྻΛฦ͢ Q. ৑௕͞͸ͳ͍͔ʁ Q. ৘ใ͸଍Γ͍ͯΔ͔ʁ

Slide 14

Slide 14 text

let string = input.message.trimWhitespaces() func trimWhitespaces() -> String Q. APIͷ໾ׂ͸ʁ Q. ࣗ਎Λมߋ͢Δ͔ʁ ༨നΛτϦϛϯάͨ͠จࣈྻΛฦ͢ ͠ͳ͍ Q. ৑௕͞͸ͳ͍͔ʁ Q. ৘ใ͸଍Γ͍ͯΔ͔ʁ FEɺJOHܗʹ͢Δ

Slide 15

Slide 15 text

let string = input.message.trimmingWhitespaces() func trimmingWhitespaces() -> String Q. APIͷ໾ׂ͸ʁ Q. ࣗ਎Λมߋ͢Δ͔ʁ ͠ͳ͍ Q. ৑௕͞͸ͳ͍͔ʁ 0, Q. ৘ใ͸଍Γ͍ͯΔ͔ʁ 0, FEɺJOHܗʹ͢Δ ༨നΛτϦϛϯάͨ͠จࣈྻΛฦ͢

Slide 16

Slide 16 text

let mail = try await Mailer.sendMail(string, to: "...") mailBox.update(mail: mail, bottom: false) let string = input.message.trimmingWhitespaces()

Slide 17

Slide 17 text

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, ...

Slide 18

Slide 18 text

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͚ͩͰ͸ͲΜͳจࣈྻͳͷ͔ར༻ଆͰ෼͔Γʹ͍͘

Slide 19

Slide 19 text

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͚ͩͰ͸ͲΜͳจࣈྻͳͷ͔ར༻ଆͰ෼͔Γʹ͍͘

Slide 20

Slide 20 text

let string = input.message.trimmingWhitespaces() mailBox.update(mail: mail, bottom: false) let mail = try await Mailer.send(string, toAddress: "...")

Slide 21

Slide 21 text

func update(mail: Mail, bottom: Bool) Q. APIͷ໾ׂ͸ʁ Q. ࣗ਎Λมߋ͢Δ͔ʁ ϝʔϧΛϝʔϧϘοΫεͷτοϓʹૠೖ͢Δ Q. ৑௕͞͸ͳ͍͔ʁ Q. ৘ใ͸଍Γ͍ͯΔ͔ʁ mailBox.update(mail: mail, bottom: false)

Slide 22

Slide 22 text

func insert(mail: Mail, bottom: Bool) Q. APIͷ໾ׂ͸ʁ Q. ࣗ਎Λมߋ͢Δ͔ʁ ϝʔϧΛϝʔϧϘοΫεͷτοϓʹૠೖ͢Δ Q. ৑௕͞͸ͳ͍͔ʁ Q. ৘ใ͸଍Γ͍ͯΔ͔ʁ mailBox.insert(mail: mail, bottom: false) ໨తޠ

Slide 23

Slide 23 text

func insertMail(_ mail: Mail, bottom: Bool) Q. APIͷ໾ׂ͸ʁ Q. ࣗ਎Λมߋ͢Δ͔ʁ ϝʔϧΛϝʔϧϘοΫεͷτοϓʹૠೖ͢Δ ͢Δ Q. ৑௕͞͸ͳ͍͔ʁ Q. ৘ใ͸଍Γ͍ͯΔ͔ʁ bottom: false͸ᐆດ mailBox.insertMail(mail, bottom: false) ໋ྩܗʹ͢Δ enumʹͯ͠ΈΔ

Slide 24

Slide 24 text

func insertMail(_ mail: Mail, at position: InsertPosition) Q. APIͷ໾ׂ͸ʁ Q. ࣗ਎Λมߋ͢Δ͔ʁ ϝʔϧΛϝʔϧϘοΫεͷτοϓʹૠೖ͢Δ ͢Δ Q. ৑௕͞͸ͳ͍͔ʁ Q. ৘ใ͸଍Γ͍ͯΔ͔ʁ Mail͸ແͯ͘΋఻ΘΔ bottom: false͸ᐆດ mailBox.insertMail(mail, at: .top) ໋ྩܗʹ͢Δ enumʹͯ͠ΈΔ

Slide 25

Slide 25 text

func insert(_ mail: Mail, at position: InsertPosition) Q. APIͷ໾ׂ͸ʁ Q. ࣗ਎Λมߋ͢Δ͔ʁ ϝʔϧΛϝʔϧϘοΫεͷτοϓʹૠೖ͢Δ ͢Δ Q. ৑௕͞͸ͳ͍͔ʁ Q. ৘ใ͸଍Γ͍ͯΔ͔ʁ Mail͸ແͯ͘΋఻ΘΔ bottom: false͸ᐆດ mailBox.insert(mail, at: .top) ໋ྩܗʹ͢Δ enumʹͯ͠ΈΔ

Slide 26

Slide 26 text

string = input.message.trimmingWhitespaces() string, toAddress: "...") mail = try await Mailer.send( let let mailBox.insert(mail, at: .top)

Slide 27

Slide 27 text

message = input.message.trimmingWhitespaces() message, toAddress: "...") mail = try await Mailer.send( let let mailBox.insert(mail, at: .top) mailBox.insert(mail, at: .top)

Slide 28

Slide 28 text

sentMail = try await Mailer.send(message, toAddress: "...") message = input.message.trimmingWhitespaces() let let mailBox.insert(sentMail, at: .top)

Slide 29

Slide 29 text

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)

Slide 30

Slide 30 text

API Design GuidelinesΛಡ΋͏ ར༻ଆͰͷ໌շ͞Λॏࢹ͠Α͏ ·ͱΊ ໌շͳAPIΛઃܭ͢ΔͨΊͷ4ͭͷ໰͍ APIͷ໾ׂɺ෭࡞༻͸͋Δ͔ɺ৘ใ͸଍Γ͍ͯΔ͔ɺ৑௕͞͸ͳ͍͔