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

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

Transcript

1. !LZNNU(.01FQBCP *OD
   &$5FDI.5(
   EC৽αʔϏεʹ͓͚Δ
   εΩʔϚϑΝʔετ։ൃ
   

   View Slide

2. ࿩͢͜ͱ
   wεΩʔϚϑΝʔετ։ൃͱ͍͏Web API࢓༷ఆٛΛ

   த৺ʹਾ͑ͨΞϓϦέʔγϣϯ։ൃͷ֓ཁ
   wεΩʔϚϑΝʔετ։ൃΛ࣮ݱ͢ΔͨΊʹඞཁͳಓ۩
   wEC৽αʔϏεͰͲͷΑ͏ʹεΩʔϚϑΝʔετ։ൃ
   Λ࣮ࢪ͍ͯ͠Δ͔
   

   View Slide

3. εΩʔϚϑΝʔετ։ൃͱ͸
   

   View Slide

4. εΩʔϚϑΝʔετ։ൃͱ͸
   wJSONΛฦ͢Web API͕ଘࡏ͢ΔΞϓϦέʔγϣϯͷ։ൃ͕ର৅
   wSPA (Single Page App)΍ϞόΠϧɺAPI୯ಠͰ΋
   wAPI࢓༷ʢεΩʔϚʣΛఆ͔ٛͯ͠ΒεΩʔϚΛ΋ͱʹ։ൃ͍ͯ͘͠
   εΩʔϚͷओͳߏ੒ཁૉ
   URL
   HTTPϝιου ϦΫΤετύϥϝʔλ
   εςʔλείʔυ ϨεϙϯεϘσΟ
   

   View Slide

5. εΩʔϚϑΝʔετ։ൃͷϑϩʔ
   εΩʔϚఆٛ
   ϑϩϯτΤϯυ
   ։ൃ&ςετ
   API
   ։ൃ&ςετ
   ݁߹ςετ
   

   View Slide

6. ·ͣҰॹʹ૬ஊ͠ͳ͕ΒεΩʔϚΛఆٛͯ͠ɺ
   εΩʔϚΛ΋ͱʹύϥϨϧʹ࣮૷ɻ݁߹ͯ͠
   ΋΄ͱΜͲෆ۩߹͸ݟ౰ͨΒͳ͍ͷͰͦͷ·
   ·ϦϦʔεɻ
   ͱͳΓɺೝࣝҧ͍΍݁߹࣌ͷτϥϒϧ͕গͳ
   ͘ͳΔͷͰՃ଎͕ظ଴Ͱ͖·͢ɻ
   εΩʔϚϑΝʔετ։ൃͷεεϝonk.ninja
   https://blog.onk.ninja/2017/09/21/schema_first_development
   

   View Slide

7. εΩʔϚϑΝʔετ։ൃͷར఺
   w։ൃऀؒͰεΩʔϚʹؔ͢ΔೝࣝΛૣظʹҰக
   wΠϯλϑΣʔε͕ܾ·͔ͬͯΒ։ൃ͢ΔͷͰɺ

   ϑϩϯτΤϯυͱAPIͷ݁߹͕੒ޭ͠΍͍͢
   wఆٛͨ͠εΩʔϚࣗମΛ׆༻ͨ͠։ൃͷޮ཰Խ͕Մೳ
   

   View Slide

8. εΩʔϚϑΝʔετ։ൃʹ
   ඞཁͳπʔϧ
   

   View Slide

9. εΩʔϚϑΝʔετ։ൃͰ΍Δ͜ͱ
   wAPIͷεΩʔϚΛఆٛ
   wεΩʔϚΛ΋ͱʹΞϓϦέʔγϣϯΛ࣮૷
   wΫϥΠΞϯτ͕ଘࡏ͢Δͱ͖͸ฒߦ։ൃ
   wαʔό͸APIͷεΩʔϚʹ४ڌ࣮ͨ͠૷ʹ͢Δ
   

   View Slide

10. wAPIͷεΩʔϚΛఆٛ
    wεΩʔϚΛ΋ͱʹΞϓϦέʔγϣϯΛ࣮૷
    wΫϥΠΞϯτ͕ଘࡏ͢Δͱ͖͸ฒߦ։ൃ
    wαʔό͸APIͷεΩʔϚʹ४ڌ࣮ͨ͠૷ʹ͢Δ
    εΩʔϚϑΝʔετ։ൃʹඞཁͳπʔϧ
    OpenAPI & Swagger tools
    Committee & RSpec
    EC৽αʔϏε΋͜ΕΒͷπʔϧͰ

    εΩʔϚϑΝʔετ։ൃͷ؀ڥΛ੔උ͍ͯͬͨ͠
    

    View Slide

11. OpenAPI & Swagger tools
    

    View Slide

12. OpenAPI
    wJSON/YAMLͰهड़Ͱ͖ΔRESTful API࢓༷هड़ͷͨΊͷ࢓༷
    w࢓༷ʹ͕ͨͬͯ͠ॻ͍ͨ΋ͷΛOpenAPIυΩϡϝϯτͱݺͿ
    
    w2017೥7݄ʹv3.0.0͕ϦϦʔε
    wରԠ͍ͯ͠Δπʔϧ͕গͳ͍ͷͰɺ΋͏͠͹Β͘͸v2.0Ͱ
    
    ਖ਼ࣜʹ͸v3.0.0͔Β
    

    View Slide

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'
    ˡΤϯυϙΠϯτͷఆٛ
    ˣϨεϙϯεߏ଄ͷఆٛ
    

    View Slide

14. Swagger tools
    • Swagger UI / Swagger Editor
    wOpenAPIυΩϡϝϯτ͔Βϒϥ΢βͰݟ΍͍͢υΩϡϝϯτΛੜ੒
    • Swagger Codegen
    wOpenAPIυΩϡϝϯτ͔Β֤छݴޠͰॻ͔ΕͨΫϥΠΞϯτͱ

    ελϒαʔόͷίʔυΛੜ੒
    wࠓճ͸ελϒαʔόΛੜ੒࣮ͯ͠API։ൃͱฒߦͨ͠ΫϥΠΞϯτ

    ։ൃΛ࣮ࢪ
    

    View Slide

15. View Slide

16. Committee & RSpec
    

    View Slide

17. લఏʛAPIυΩϡϝϯτͷ৴པੑ୲อ
    wAPIͷυΩϡϝϯτͷ࣮૷ͱͷဃ཭Λ๷ࢭͯ͠৴པੑΛ୲อ͍ͨ͠
    wϑϩϯτʗ"1*݁߹࣌ͷෆ۩߹Λ͞ΒʹݮΒ͢
    wAPIΛ࢖͏ਓɺকདྷ։ൃʹՃΘΔਓɺະདྷͷࣗ෼͕ͨͪॿ͔Δ
    wOpenAPI͕͋Ε͹εΩʔϚΛར༻ͨ͠APIͷςετ͕Մೳ
    w࣮ࡍͷϨεϙϯεͱεΩʔϚ͕Ұக͢Δ͔νΣοΫ͢Ε͹Α͍
    wͰ͖Δ͚ͩػցతʹରࡦָ͕ͯ͠Ͱ͖ΔͱΑ͍
    

    View Slide

18. Committeehttps://github.com/interagent/committee
    wJSON SchemaΛར༻ͨ͠APIαʔόͷͨΊͷRack Middleware܈
    wϦΫΤετʗϨεϙϯεJSONͷߏ଄όϦσʔγϣϯ
    wελϒαʔό
    wςετͰར༻Ͱ͖ΔϨεϙϯεߏ଄όϦσʔγϣϯ༻ͷϝιου
    

    View Slide

19. JSON Schemahttp://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ʹର͢ΔόϦσʔγϣϯ͕Մೳ
    

    View Slide

20. JSON Schemaͷ׆༻
    wOpenAPIυΩϡϝϯτͷϨεϙϯεهड़͸JSON SchemaΛར༻Մೳ
    wCommittee
    
    wJSON SchemaΛར༻ͯ͠όϦσʔγϣϯΛ࣮ߦ
    wOpenAPI v2.0ΛಡΈࠐΜͰɺͦΕͧΕͷΤϯυϙΠϯτʹରԠ͢Δ
    ϨεϙϯεΛೝࣝՄೳ
    w0QFO"1*υΩϡϝϯτʹॻ͍ͨεΩʔϚͰAPIͷςετ͕Ͱ͖Δʂ
    

    View Slide

21. Committeeͷબఆཧ༝
    wର߅അ͸Apivoreͱ͍͏RSpecͱ౷߹ͨ͠JSONͷόϦσʔγϣϯ༻
    gem https://github.com/westfieldlabs/apivore
    
    wRSpecͱີ݁߹ͳײ͡ςετίʔυͷϝϯς͕΍΍ͭΒͦ͏
    • Committee
    
    w֤Rack middleware͕ૄͳ࡞Γʹͳ͍ͬͯͯಋೖ͠΍͍͢
    wίʔυ͕ಡΈ΍͘͢HerokuϓϩμΫτͱ͍͏҆৺ײ
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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͕৯͍ҧ͏ͱ͖ʹࢦఠͯ͘͠ΕΔΑ͏ʹͳͬͨ
    

    View Slide

25. εΩʔϚϑΝʔετ։ൃͷ࣮ྫ
    

    View Slide

26. ʮεΩʔϚϑΝʔετ։ൃͷ࣮ྫʯͷਅ࣮
    w࣮͸ʮεΩʔϚϑΝʔετ։ൃ΍Δͧʂʂʯͱ͔ݴͬͨ͜ͱͳ͍
    wOpenAPIΛಋೖ͠ͳ͕ΒΈΜͳͰ΍͍ͬͯͨΒͦΕͬΆ͘

    ͳ͍ͬͯͨ
    wRubyKaigi 2017Ͱ֓೦ʹ໊લΛ͚ͭͯ΋Βͬͨײ͡
    wref: API Development in 2017 - RubyKaigi 2017

    http://rubykaigi.org/2017/presentations/onk.html
    

    View Slide

27. ৽αʔϏε։ൃ࣌ͷྲྀΕ
    APIఆٛ
    εʔύʔ
    ϨϏϡʔ
    ։ൃͱ
    ςετ
    ݁߹
    

    View Slide

28. APIఆٛ
    wඞཁͳػೳͷཁ݅ʹج͍ͮͯAPIΛఆٛ
    wYAMLͰॻ͘ͱOpenAPIυΩϡϝϯτΛੜ੒Ͱ͖Δ

    ߏ੒
    wϑϩϯτʗAPIͲͪΒͷ୲౰Ͱ΋ඞཁͳΒ୭͔͕ॻ͘
    

    View Slide

29. εʔύʔϨϏϡʔ
    wAPIఆ͕ٛॻ͚ͨΒSlackͰ੠͔͚ͯσεΫ·ΘΓͰಥൃϨϏϡʔ
    wϨϏϡʔϙΠϯτ
    wURLɺϦιʔεͷ੾Γ͔ͨɺ໋໊ɺύϥϝʔλʗϨεϙϯεଐੑͷ
    աෆ଍ɺεςʔλείʔυͳͲ
    w͸͡Ίʹٞ࿦͢Δ͜ͱͰ࢓༷͕಄ͷதͰ੔ཧ͞ΕΔޮՌ΋͋Γ
    

    View Slide

30. ։ൃͱςετ
    wAPI͸APIఆٛΛ΋ͱʹ࣮૷
    wϑϩϯτΤϯυ͸Swagger CodegenͰੜ੒ͨ͠ελϒαʔόΛ

    ࢖ͬͯAPIͱฒߦ࡞ۀͰ࣮૷
    wCommitteeʹΑΔςετ͸࠷ۙೖΕͨͷͰ·ͩͦΕ΄Ͳ׆༂ͯ͠

    ͳ͍ʜʜ
    wࠓޙʹظ଴
    

    View Slide

31. ஫ҙ఺ʛϨεϙϯεͷJSON
    wಉ͡ϦιʔεΛද͢JSONΦϒδΣΫτʹ͍ͭͯ͸APIશମͰߏ଄Λἧ͑ͯ
    ͍͘͜ͱΛઃܭ࣌ʗϨϏϡʔ࣌ʹҙࣝͨ͠΄͏͕Α͍
    waddressͱ͍͏JSONΦϒδΣΫτ͕৔ॴʹΑͬͯnameʢडऔਓࢦ໊ʣ
    Λ͍࣋ͬͯͨΓ͍࣋ͬͯͳ͔ͬͨΓʜʜ
    w΋͘͠͸࢓૊Έͱ੍ͯ͠໿ΛՃ͑Δ
    w͋ΔϦιʔεதͷωετͨ͠ΦϒδΣΫτΛඞͣผͷϦιʔεʹ͢Δ
    wref: RESTful Web APIΛݫີͳϦιʔεࢦ޲ʹ͢Δ- Qiita

    https://qiita.com/qsona/items/f7ef78ddbbc2873d1d13
    

    View Slide

32. ·ͱΊ
    

    View Slide

33. ·ͱΊ
    wεΩʔϚϑΝʔετ։ൃΛ༻͍ͨΞϓϦέʔγϣϯ։ൃΛ঺հ
    wOpenAPI͕޿·ͬͯAPIεΩʔϚ·ΘΓͷࣄྫ΍ఆ൪πʔϧ͕ἧͬͯ
    ͖ͨͷ͕ॏཁ
    w͍·ͦ͜εΩʔϚϑΝʔετ։ൃΛҙࣝ͢ΔͱΑ͍ͷͰ͸ͳ͍͔
    

    View Slide