EC新サービスにおけるスキーマファースト開発 / Schema First Development in the New EC Service

EC Tech MTG #4（GMOペパボEC事業部の社内勉強会）のための資料です

Transcript

1. !LZNNU
   
   (.0
   1FQBCP
   *OD
   
   &$
   5FDI.5(
    EC৽αʔϏεʹ͓͚Δ
   εΩʔϚϑΝʔετ։ൃ
2. ࿩͢͜ͱ wεΩʔϚϑΝʔετ։ൃͱ͍͏Web API࢓༷ఆٛΛ
 த৺ʹਾ͑ͨΞϓϦέʔγϣϯ։ൃͷ֓ཁ
   wεΩʔϚϑΝʔετ։ൃΛ࣮ݱ͢ΔͨΊʹඞཁͳಓ۩
   wEC৽αʔϏεͰͲͷΑ͏ʹεΩʔϚϑΝʔετ։ൃ Λ࣮ࢪ͍ͯ͠Δ͔
3. εΩʔϚϑΝʔετ։ൃͱ͸
4. εΩʔϚϑΝʔετ։ൃͱ͸ wJSONΛฦ͢Web API͕ଘࡏ͢ΔΞϓϦέʔγϣϯͷ։ൃ͕ର৅
   wSPA (Single Page App)
   ΍ϞόΠϧɺAPI୯ಠͰ΋
   wAPI࢓༷ʢεΩʔϚʣΛఆ͔ٛͯ͠ΒεΩʔϚΛ΋ͱʹ։ൃ͍ͯ͘͠ εΩʔϚͷओͳߏ੒ཁૉ URL HTTPϝιου ϦΫΤετύϥϝʔλ εςʔλείʔυ ϨεϙϯεϘσΟ
5. εΩʔϚϑΝʔετ։ൃͷϑϩʔ εΩʔϚఆٛ ϑϩϯτΤϯυ
   ։ൃ
   &
   ςετ API ։ൃ
   &
   ςετ ݁߹ςετ
6. ·ͣҰॹʹ૬ஊ͠ͳ͕ΒεΩʔϚΛఆٛͯ͠ɺ εΩʔϚΛ΋ͱʹύϥϨϧʹ࣮૷ɻ݁߹ͯ͠ ΋΄ͱΜͲෆ۩߹͸ݟ౰ͨΒͳ͍ͷͰͦͷ· ·ϦϦʔεɻ
   ͱͳΓɺೝࣝҧ͍΍݁߹࣌ͷτϥϒϧ͕গͳ ͘ͳΔͷͰՃ଎͕ظ଴Ͱ͖·͢ɻ εΩʔϚϑΝʔετ։ൃͷεεϝ
   
   onk.ninja
   https://blog.onk.ninja/2017/09/21/schema_first_development
7. εΩʔϚϑΝʔετ։ൃͷར఺ w։ൃऀؒͰεΩʔϚʹؔ͢ΔೝࣝΛૣظʹҰக
   wΠϯλϑΣʔε͕ܾ·͔ͬͯΒ։ൃ͢ΔͷͰɺ
 ϑϩϯτΤϯυͱAPIͷ݁߹͕੒ޭ͠΍͍͢
   wఆٛͨ͠εΩʔϚࣗମΛ׆༻ͨ͠։ൃͷޮ཰Խ͕Մೳ
8. εΩʔϚϑΝʔετ։ൃʹ
   ඞཁͳπʔϧ
9. εΩʔϚϑΝʔετ։ൃͰ΍Δ͜ͱ wAPIͷεΩʔϚΛఆٛ
   wεΩʔϚΛ΋ͱʹΞϓϦέʔγϣϯΛ࣮૷
   wΫϥΠΞϯτ͕ଘࡏ͢Δͱ͖͸ฒߦ։ൃ
   wαʔό͸APIͷεΩʔϚʹ४ڌ࣮ͨ͠૷ʹ͢Δ
10. wAPIͷεΩʔϚΛఆٛ
    wεΩʔϚΛ΋ͱʹΞϓϦέʔγϣϯΛ࣮૷
    wΫϥΠΞϯτ͕ଘࡏ͢Δͱ͖͸ฒߦ։ൃ
    wαʔό͸APIͷεΩʔϚʹ४ڌ࣮ͨ͠૷ʹ͢Δ εΩʔϚϑΝʔετ։ൃʹඞཁͳπʔϧ OpenAPI & Swagger tools Committee & RSpec EC৽αʔϏε΋͜ΕΒͷπʔϧͰ
 εΩʔϚϑΝʔετ։ൃͷ؀ڥΛ੔උ͍ͯͬͨ͠
11. OpenAPI & Swagger tools
12. OpenAPI wJSON/YAMLͰهड़Ͱ͖ΔRESTful API࢓༷هड़ͷͨΊͷ࢓༷
    w࢓༷ʹ͕ͨͬͯ͠ॻ͍ͨ΋ͷΛOpenAPIυΩϡϝϯτͱݺͿ
    
    w2017೥7݄ʹv3.0.0͕ϦϦʔε
    wରԠ͍ͯ͠Δπʔϧ͕গͳ͍ͷͰɺ΋͏͠͹Β͘͸v2.0Ͱ 
    ਖ਼ࣜʹ͸v3.0.0͔Β
13. OpenAPIυΩϡϝϯτͷྫʢൈਮʣ definitions: Shipment: type: object properties: id: type: integer example: 1 shipped_at: type: - string - "null" format: date-time example: 2017-07-10T12:00:00Z paths: /admin/shipments/{shipmentId}: get: parameters: - shipmentId: in: path name: shipmentId type: integer required: true responses: '200': schema: type: object properties: shipment: $ref: '#/definitions/Shipment' ˡΤϯυϙΠϯτͷఆٛ ˣϨεϙϯεߏ଄ͷఆٛ
14. Swagger tools • Swagger UI / Swagger Editor wOpenAPIυΩϡϝϯτ͔Βϒϥ΢βͰݟ΍͍͢υΩϡϝϯτΛੜ੒
    • Swagger Codegen wOpenAPIυΩϡϝϯτ͔Β֤छݴޠͰॻ͔ΕͨΫϥΠΞϯτͱ
 ελϒαʔόͷίʔυΛੜ੒
    wࠓճ͸ελϒαʔόΛੜ੒࣮ͯ͠API։ൃͱฒߦͨ͠ΫϥΠΞϯτ
 ։ൃΛ࣮ࢪ
16. Committee & RSpec
17. લఏʛAPIυΩϡϝϯτͷ৴པੑ୲อ wAPIͷυΩϡϝϯτͷ࣮૷ͱͷဃ཭Λ๷ࢭͯ͠৴པੑΛ୲อ͍ͨ͠
    wϑϩϯτʗ"1*݁߹࣌ͷෆ۩߹Λ͞ΒʹݮΒ͢
    wAPIΛ࢖͏ਓɺকདྷ։ൃʹՃΘΔਓɺະདྷͷࣗ෼͕ͨͪॿ͔Δ
    wOpenAPI͕͋Ε͹εΩʔϚΛར༻ͨ͠APIͷςετ͕Մೳ
    w࣮ࡍͷϨεϙϯεͱεΩʔϚ͕Ұக͢Δ͔νΣοΫ͢Ε͹Α͍
    wͰ͖Δ͚ͩػցతʹରࡦָ͕ͯ͠Ͱ͖ΔͱΑ͍
18. Committee
    https://github.com/interagent/committee wJSON SchemaΛར༻ͨ͠APIαʔόͷͨΊͷRack Middleware܈
    wϦΫΤετʗϨεϙϯεJSONͷߏ଄όϦσʔγϣϯ
    wελϒαʔό
    wςετͰར༻Ͱ͖ΔϨεϙϯεߏ଄όϦσʔγϣϯ༻ͷϝιου
19. JSON Schema
    http://json-schema.org w ͋ΔJSONͷߏ଄Λنఆ͢Δʢͭ·ΓεΩʔϚʣJSON type: object properties: id: type: string email: type: string role: type: array items: type: string enum: - admin - normal // όϦσʔγϣϯOK { "id": "1", "email": "foo@example.com", "role": "normal" } // όϦσʔγϣϯNGʢid͕integerʣ { "id": 1 "email": "foo@example.com" } id, email, role
    Λଐੑʹ࣋ͭJSON Schema JSONʹର͢ΔόϦσʔγϣϯ͕Մೳ
20. JSON Schemaͷ׆༻ wOpenAPIυΩϡϝϯτͷϨεϙϯεهड़͸JSON SchemaΛར༻Մೳ
    wCommittee wJSON SchemaΛར༻ͯ͠όϦσʔγϣϯΛ࣮ߦ
    wOpenAPI v2.0ΛಡΈࠐΜͰɺͦΕͧΕͷΤϯυϙΠϯτʹରԠ͢Δ ϨεϙϯεΛೝࣝՄೳ
    w0QFO"1*υΩϡϝϯτʹॻ͍ͨεΩʔϚͰAPIͷςετ͕Ͱ͖Δʂ
21. Committeeͷબఆཧ༝ wର߅അ͸Apivoreͱ͍͏RSpecͱ౷߹ͨ͠JSONͷόϦσʔγϣϯ༻ gem
    https://github.com/westfieldlabs/apivore
    wRSpecͱີ݁߹ͳײ͡
    
    ςετίʔυͷϝϯς͕΍΍ͭΒͦ͏
    • Committee w֤Rack middleware͕ૄͳ࡞Γʹͳ͍ͬͯͯಋೖ͠΍͍͢
    wίʔυ͕ಡΈ΍͘͢HerokuϓϩμΫτͱ͍͏҆৺ײ
22. ςετ΁ͷ૊ΈࠐΈ wAPIͷςετͰ͸RSpecͷrequest specΛॻ͘
    wrequest specΛॻ͍ͨΒউखʹJSON SchemaͰόϦσʔγϣϯͯ͠ ΄͍͠ describe 'GET /shipments/:id' do it 'returns 200 OK' do get "/shipments/#{shipment.id}" expect(response.status).to eq 200 end end
23. request spec࣮ߦ࣌ͷόϦσʔγϣϯ describe 'GET /shipments/:id' do it 'returns 200 OK' do get "/shipments/#{shipment.id}" end end HTTPϦΫΤετΛൃߦͨ͋͠ͱʹϨεϙϯεͷJSONΛCommitteeͰ
 νΣοΫ
    assert_schema_conform
    ͢ΔΑ͏ʹॲཧࠩ͠ସ͑ ։ൃ࣌ʹεΩʔϚʹΑΔνΣοΫΛҙࣝ͠ͳ͍ͰΑ͘ͳͬͨʂ # ActionDispatch::Integration::Sessionʹprepend def process(*args) super *args assert_schema_conform end ˞งғؾͳͷͰৄࡉ͸ϒϩάݟͯͶ
    http://blog.kymmt.com/entry/auto-json-validation-with-committee
24. όϦσʔγϣϯࣦഊ࣌ͷྫ 1) Users GET /users/:id conforms to the schema Failure/Error: assert_schema_conform Committee::InvalidResponse: Invalid response. #: failed schema #/properties//users/{userId}/properties/GET: "email" wasn't supplied. request specΛॻ͍͓͚ͯ͹ɺOpenAPIυΩϡϝϯτͷϨεϙϯεεΩʔϚͱ
 ࣮ࡍͷϨεϙϯεJSON͕৯͍ҧ͏ͱ͖ʹࢦఠͯ͘͠ΕΔΑ͏ʹͳͬͨ
    
25. εΩʔϚϑΝʔετ։ൃͷ࣮ྫ
26. ʮεΩʔϚϑΝʔετ։ൃͷ࣮ྫʯͷਅ࣮ w࣮͸ʮεΩʔϚϑΝʔετ։ൃ΍Δͧʂʂʯͱ͔ݴͬͨ͜ͱͳ͍
    wOpenAPIΛಋೖ͠ͳ͕ΒΈΜͳͰ΍͍ͬͯͨΒͦΕͬΆ͘
 ͳ͍ͬͯͨ
    wRubyKaigi 2017Ͱ֓೦ʹ໊લΛ͚ͭͯ΋Βͬͨײ͡
    wref: API Development in 2017 - RubyKaigi 2017
 http://rubykaigi.org/2017/presentations/onk.html
27. ৽αʔϏε։ൃ࣌ͷྲྀΕ APIఆٛ εʔύʔ
    ϨϏϡʔ ։ൃͱ
    ςετ ݁߹
28. APIఆٛ wඞཁͳػೳͷཁ݅ʹج͍ͮͯAPIΛఆٛ
    wYAMLͰॻ͘ͱOpenAPIυΩϡϝϯτΛੜ੒Ͱ͖Δ
 ߏ੒
    wϑϩϯτʗAPIͲͪΒͷ୲౰Ͱ΋ඞཁͳΒ୭͔͕ॻ͘
29. εʔύʔϨϏϡʔ wAPIఆ͕ٛॻ͚ͨΒSlackͰ੠͔͚ͯσεΫ·ΘΓͰಥൃϨϏϡʔ
    wϨϏϡʔϙΠϯτ
    wURLɺϦιʔεͷ੾Γ͔ͨɺ໋໊ɺύϥϝʔλʗϨεϙϯεଐੑͷ աෆ଍ɺεςʔλείʔυͳͲ
    w͸͡Ίʹٞ࿦͢Δ͜ͱͰ࢓༷͕಄ͷதͰ੔ཧ͞ΕΔޮՌ΋͋Γ
30. ։ൃͱςετ wAPI͸APIఆٛΛ΋ͱʹ࣮૷
    wϑϩϯτΤϯυ͸Swagger CodegenͰੜ੒ͨ͠ελϒαʔόΛ
 ࢖ͬͯAPIͱฒߦ࡞ۀͰ࣮૷
    wCommitteeʹΑΔςετ͸࠷ۙೖΕͨͷͰ·ͩͦΕ΄Ͳ׆༂ͯ͠
 ͳ͍ʜʜ
    wࠓޙʹظ଴
31. ஫ҙ఺ʛϨεϙϯεͷJSON wಉ͡ϦιʔεΛද͢JSONΦϒδΣΫτʹ͍ͭͯ͸APIશମͰߏ଄Λἧ͑ͯ ͍͘͜ͱΛઃܭ࣌ʗϨϏϡʔ࣌ʹҙࣝͨ͠΄͏͕Α͍
    waddressͱ͍͏JSONΦϒδΣΫτ͕৔ॴʹΑͬͯnameʢडऔਓࢦ໊ʣ Λ͍࣋ͬͯͨΓ͍࣋ͬͯͳ͔ͬͨΓʜʜ
    w΋͘͠͸࢓૊Έͱ੍ͯ͠໿ΛՃ͑Δ
    w͋ΔϦιʔεதͷωετͨ͠ΦϒδΣΫτΛඞͣผͷϦιʔεʹ͢Δ
    wref: RESTful Web API
    ΛݫີͳϦιʔεࢦ޲ʹ͢Δ
    - Qiita
 https://qiita.com/qsona/items/f7ef78ddbbc2873d1d13
32. ·ͱΊ
33. ·ͱΊ wεΩʔϚϑΝʔετ։ൃΛ༻͍ͨΞϓϦέʔγϣϯ։ൃΛ঺հ
    wOpenAPI͕޿·ͬͯAPIεΩʔϚ·ΘΓͷࣄྫ΍ఆ൪πʔϧ͕ἧͬͯ ͖ͨͷ͕ॏཁ
    w͍·ͦ͜εΩʔϚϑΝʔετ։ൃΛҙࣝ͢ΔͱΑ͍ͷͰ͸ͳ͍͔