API 設計討論

[yurenju]

最近正在補齊一些測試案例，我覺得是時候來討論一下 API 要如何設計了，包含支援 JSON-LD #15 也可以在這邊一併討論。

先來看看一個典型的案例：

https://github.com/g0v/labor-standards-tw/blob/master/features/overtime-pay.feature#L18-L22

  場景: 違法狀況下平日的加班費
    假設 一個月薪制的勞工，平均時薪為 150 元
    當 在平常日
    並且 工作 13 小時
    而且 計算加班費時

    那麼 根據勞基法 24 條
    而且 他的加班費為 1150 元
    而且 違反勞基法 32 條

這是一個計算加班費的 function，輸入與輸出有：

輸入：

• 平均時薪 150
• 平常日（有可能是休息日、例假日）
• 工作 13 小時

輸出：

• 加班費
• 根據哪條法律
• 違反哪條法律
• 罰款（這個沒有寫在測試案例裡面，但是應該要有）

所以 API 可以設計成：

overtimePay (hourlySalary, type, hours) {}

使用起來可以是：

const result = std.overtimePay(150, std.TYPE_DAY_REGULAR_DAY, 13)

而回傳值可以是：

{
  "legal": false,
  "value": 1150,
  "according": [ "LSA-24" ],
  "fines": [
    {"min": 20000, "max": 100000, "according": ["LSA-78"]}
  ]
}

其中 value 放通用的回傳值，根據不同 API 可能會有不同型態。比如檢測特定條件是否可以退休時，value 會是 boolean 值。

不過如果套用 JSON-LD 可能還會需要一些 metadata 的欄位如 @context 跟 @type。我還沒想得很清楚，如果大家有什麼意見都請提出。

[yurenju]

跟朋友聊過後，覺得也可以用 method chaining 的方式設計 API，比如說驗證童工的部分：

const { Labor, Education, Day } = require('../../src/index')
let labor = Labor()

// 檢查是否為童工
labor.age(14)
     .graduate(Education.JUNIOR_HIGH_SCHOOL, false)
     .authorityAgree(true)
expect(labor.isChildLabor()).eq(true)

// 是否可以在例假日工作
labor.workAt(Day.REGULAR_LEAVE)
const result = labor.validate()
const violation = result.violate()
const penalty = result.penalize()
expect(result.legal).eq(false)
expect(violation[0].id).eq('LSA-47')
expect(penalty[0].id).eq('LSA-77')

會在探索一下有什麼適合的設計方式。

[yurenju]

這幾週我又稍微看了一下 functional programming 的 module 設計方式，我覺得這個專案還是比較適合用 OO 的方式設計，也就是用 labor class 產生 instance, 而 instance 裡面會有 property 跟 method。晚點我會在一個 branch 裡面先寫空的 Labor.js 來看看這個類別應該要長怎樣比較好，使用上應該會怎樣。

[yurenju]

已設計完成。