G.5 模組化與函式設計:def 函式封裝、參數契約與 CIF 報價模組
學完本節,你能夠:
- 用
def把一段商業計算封裝成函式,並分辨return(交回結果)與print(只顯示)。 - 判斷哪些參數適合給預設值、哪些必須由呼叫者提供,並用型別提示與說明文字(docstring)寫清楚函式的「契約」。
- 把 E.4 的 CIF 公式寫成函式,在輸入不合理時停止,並用同一個函式批次產生多個目的港的報價。
壹、開場情境:同一個公式,三個版本
📌 以下為教學情境(依實務改編)。
E.4 的 cif_quotation.py 在公司裡傳開了。一個月後,小安發現同一個 CIF 公式出現在三個地方:
| 誰複製的 | 改了什麼 | 結果 |
|---|---|---|
| 業務 A | 原封不動 | 正確 |
| 業務 B | 嫌移項公式難懂,改成 (FOB + 運費) × 1.1 × 費率 |
每張報價的保險費都少算 |
| 報價系統 | 保險費率改成 0.5%,但只改了其中一處 | 同一張報價單前後數字不一致 |
公式本身沒錯,錯在它被複製貼上了三次。之後只要規則一改(例如投保加成從 110% 改成 120%),就得找出每一份複本逐一修改,漏掉一份就出錯。
本節要解決的問題: 怎麼把公式寫成「只有一份、大家都呼叫它」的標準模組?
貳、為什麼要用函式:把計算寫成一份標準作業程序
函式就像公司的 SOP:規定好要給什麼(輸入)、照什麼步驟做(處理)、交出什麼(輸出)。所有人都呼叫同一個函式,規則只需要在一個地方維護,這個原則叫 DRY(Don't Repeat Yourself,不要重複)。
fob、freight、insurance_rate"] --> F["def cif_quote(...)
檢查輸入 → 計算"] F --> Out["輸出(return)
fob、freight、insurance、cif"] F -.->|"輸入不合理"| Err["raise ValueError
停止,不產生報價"]
1. def 與 return
def calculate_margin(revenue, cost):
"""回傳毛利率(小數)。毛利率 = (收入 − 成本) ÷ 收入"""
if revenue <= 0:
raise ValueError("收入必須大於 0,無法計算毛利率")
return (revenue - cost) / revenue
# 第 1.1 節的 A 款鍵盤:報價 €100
at_quote = calculate_margin(100 * 35.0, 2800) # 報價當天匯率 35.0
at_settle = calculate_margin(100 * 31.5, 2800) # 結匯當天匯率 31.5
print(f"報價時毛利率 {at_quote:.1%},結匯時 {at_settle:.1%}")
print(f"少了 {(at_quote - at_settle) * 100:.1f} 個百分點")
報價時毛利率 20.0%,結匯時 11.1%
少了 8.9 個百分點
| 語法 | 作用 |
|---|---|
def 名稱(參數): |
定義函式;底下縮排的內容是函式本體 |
return 值 |
把結果交回給呼叫的地方,函式到此結束 |
raise ValueError("訊息") |
輸入不合理時停止,並說明原因 |
名稱(引數) |
呼叫函式 |
raise 比回傳一個假的 0 更安全:如果收入是 0 時回傳毛利率 0,呼叫者可能把它當成真的數字繼續用;raise 則讓錯誤無法被忽略。
常見錯誤:用 print 代替 return
def show_margin(revenue, cost):
print((revenue - cost) / revenue) # 只印出來,沒有交回
result = show_margin(3150, 2800)
print(result)
0.1111111111111111
None
⚠️ print 不等於 return
return的函式交回的是None,其他程式拿不到結果,也就無法再拿去計算或存檔。
2. 預設參數:哪些數字可以「預設」?
def calculate_vat(amount, tax_rate=0.05):
"""回傳營業稅額;不指定稅率時,採台灣營業稅 5%"""
return amount * tax_rate
print(calculate_vat(1000)) # 用預設 5%
print(calculate_vat(1000, 0.19)) # 德國標準稅率 19%
50.0
190.0
預設值是一種商業決策,不是寫程式的方便:
| 參數 | 給預設值? | 理由 |
|---|---|---|
| 台灣營業稅率 5% | ✅ | 法定稅率,很少變動 |
| 保險費率 0.3% | ✅ | 公司與保險公司的常用費率,個案可覆蓋 |
| 投保加成 110% | ✅ | 國際慣例 |
| 匯率 | 🛑 | 每天變動;預設值等於用過期匯率報價(E.5 的 --rate 必填也是這個理由) |
| FOB、運費 | 🛑 | 每筆交易都不同,沒有合理的預設 |
3. 型別提示與 docstring:把契約寫在函式上
def convert_to_twd(amount: float, rate: float) -> int:
"""
把外幣金額換算成新台幣。
參數:
amount: 外幣金額
rate: 當日匯率(必填,不設預設值,避免用到過期匯率)
回傳:
新台幣金額,四捨五入到整數
"""
return round(amount * rate)
print(convert_to_twd(48961.57, 32.2))
1576563
amount: float 表示「這裡應該給小數」,-> int 表示「會交回整數」。Python 不會強制檢查型別提示,但同事、編輯器與 AI 助手都看得懂。三引號 """ 內的說明文字稱為 docstring,在 REPL 輸入 help(convert_to_twd) 就能看到。
4. 區域變數:函式內的東西留在函式內
def apply_discount(price):
discount = 0.10 # 區域變數:只活在函式裡
return price * (1 - discount)
print(apply_discount(1000))
print(discount)
900.0
Traceback (most recent call last):
...(中間顯示出錯的行號,略)
NameError: name 'discount' is not defined
函式內建立的變數,函式結束就消失,不會汙染外面。反過來,也不要在函式內用 global 去修改外面的變數:那會讓函式的結果取決於「外面剛好是什麼值」,同樣的輸入可能算出不同結果,很難除錯。函式需要什麼,就從參數拿;算出什麼,就用 return 交回。
參、把規則寫下來:CIF 報價函式的契約
| 項目 | 規格 |
|---|---|
| 函式名稱 | cif_quote |
| 必填參數 | fob(FOB 貨價)、freight(海運運費),單位美元,都必須 > 0 |
| 有預設值的參數 | insurance_rate=0.003(0.3%)、insured_markup=1.1(110%) |
| 公式 | 與 E.4 相同:CIF = (FOB + 運費) ÷ (1 − 投保加成 × 保險費率) |
| 數字一致 | CIF 四捨五入到小數兩位;保險費 = CIF − FOB − 運費,確保報價單上三項加總剛好等於 CIF |
| 例外 | FOB 或運費 ≤ 0、保險費率不在 0~10% 之間 → raise ValueError,不產生報價 |
| 回傳 | 字典:fob、freight、insurance、cif |
為什麼投保金額是 CIF 的 110%?Incoterms 2020 規定,CIF 條件下賣方至少要按契約價金的 110% 投保,且最低承保範圍為協會貨物條款 (C);多出的 10% 一般解釋為保障買方的預期利潤與費用。
肆、寫出來
在 TradeLab 資料夾建立 cif_module.py:
# cif_module.py:把 E.4 的 CIF 公式封裝成函式,批次產生報價
def cif_quote(fob: float, freight: float,
insurance_rate: float = 0.003,
insured_markup: float = 1.1) -> dict:
"""
由 FOB 貨價與運費計算 CIF 報價(單位:美元)。
投保金額 = CIF × insured_markup(慣例 110%)
CIF = (FOB + 運費) ÷ (1 − insured_markup × insurance_rate)
參數:
fob: FOB 貨價,必須 > 0
freight: 海運運費,必須 > 0
insurance_rate: 保險費率,預設 0.3%,須介於 0 與 10% 之間
insured_markup: 投保加成,預設 1.1
回傳:
dict,含 fob、freight、insurance、cif,皆四捨五入到小數兩位
"""
# 1. 輸入檢查:不合理就停止,不產生報價
if fob <= 0 or freight <= 0:
raise ValueError(f"FOB 與運費必須大於 0(收到 fob={fob}, freight={freight})")
if not 0 < insurance_rate < 0.1:
raise ValueError(f"保險費率 {insurance_rate} 不合理,請核對保單")
# 2. 計算(與 E.4 同一個公式)
cif = round((fob + freight) / (1 - insured_markup * insurance_rate), 2)
insurance = round(cif - fob - freight, 2) # 用減的,保證三項加總剛好等於 CIF
# 3. 回傳結構化結果,交給呼叫者決定怎麼顯示或存檔
return {"fob": fob, "freight": freight, "insurance": insurance, "cif": cif}
# ===== 使用範例:同一批貨,三個目的港(運費為教學用假設值)=====
FOB = 45000.0
FREIGHT_BY_PORT = {"Hamburg": 3800.0, "Los Angeles": 2600.0, "Tokyo": 1200.0}
print(f"{'Port':<12}{'Freight':>10}{'Insurance':>10}{'CIF':>12}")
for port, freight in FREIGHT_BY_PORT.items():
q = cif_quote(FOB, freight)
print(f"{port:<12}{q['freight']:>10,.2f}{q['insurance']:>10,.2f}{q['cif']:>12,.2f}")
執行結果:
Port Freight Insurance CIF
Hamburg 3,800.00 161.57 48,961.57
Los Angeles 2,600.00 157.60 47,757.60
Tokyo 1,200.00 152.96 46,352.96
Hamburg 這一列與 E.4 的結果(保險費 161.57、CIF 48,961.57)完全相同:同一個公式,現在只有一份。
🔍 驗收重點 - 公式是否與 E.4 相同,除以
(1 − 1.1 × 費率),而不是用(FOB + 運費) × 1.1 × 費率近似? - 匯率、FOB、運費是否都沒有預設值? - 輸入不合理時是raise,而不是回傳 0 或空字典? - 每一列:運費 + 保險費 + 45,000 是否剛好等於 CIF?
伍、跑跑看、壞給你看
在檔案最後加一行測試,跑完再刪掉。
| 實驗 | 操作 | 預期結果 | 想想看 |
|---|---|---|---|
| ① 運費漏填 | cif_quote(45000.0, 0) |
ValueError: FOB 與運費必須大於 0(收到 fob=45000.0, freight=0) |
錯誤訊息有沒有告訴你「哪裡錯、收到什麼」? |
| ② 覆蓋預設值 | print(cif_quote(45000.0, 3800.0, insurance_rate=0.005)) |
保險費 269.88、CIF 49,069.88(與 E.4 實驗 ③ 相同) | 預設值讓常見情況少打字,特殊情況仍可指定 |
| ③ 參數位置放錯 | cif_quote(45000.0, 3800.0, 1.1)(想指定投保加成,卻沒寫參數名稱) |
ValueError: 保險費率 1.1 不合理,請核對保單 |
1.1 被當成第 3 個參數 insurance_rate。為什麼用 insured_markup=1.1 這種寫法比較安全? |
| ④ 業務 B 的簡化公式 | 在 REPL 算 (45000 + 3800) * 1.1 * 0.003 |
161.04000000000002,比函式的 161.57 少 0.53 |
這個錯誤只要修函式一處,所有呼叫者就同時修好 |
陸、回到情境
三份複本換成一個 cif_quote():業務的試算、報價系統、未來的 ERP,都呼叫同一個函式。投保加成若要改成 120%,只要改預設值一處;有人傳入不合理的數字,函式會停下來說明原因,而不是交出一張看似正常的報價單。
| 限制 | 後果 | 在哪一節解決 |
|---|---|---|
| 函式還放在單一檔案裡 | 其他程式要用,仍得複製 | 存成模組後用 import 引用(第 4 章起的程式會大量使用) |
| 沒有自動化測試 | 有人改壞公式,要等客戶發現 | 可以套用第 5 章的 pytest 寫法,為 cif_quote() 寫測試 |
| CIF 不是買方的總成本 | 目的港費用、進口關稅等仍由買方負擔 | 進口成本試算見 E.5 的關稅試算 |
本節小結
- 重複出現的計算寫成函式,規則只在一處維護(DRY)。
return交回結果,print只是顯示;輸入不合理用raise停止,不回傳假值。- 預設值是商業決策:法定稅率、慣例可以預設;匯率、每筆交易的金額不行。
- 型別提示與 docstring 寫清楚函式的契約;呼叫時用參數名稱,避免位置放錯。
柒、練習
- 改數字(5 分鐘):Hamburg 的運費漲到 USD 5,200。用
cif_quote()算出新的保險費與 CIF。(答案:166.21;50,366.21,與 E.4 練習 1 相同) - 加功能(20 分鐘):寫一個
cif_quote_twd(fob, freight, rate),在內部呼叫cif_quote()與convert_to_twd(),回傳 CIF 的台幣金額。先寫契約(參數、哪些必填、例外怎麼處理、回傳什麼),再請 AI 實作,用匯率 32.2 驗算 Hamburg 的結果是否為 NT$ 1,576,563。 - 管理反思(討論):開場三份複本中,業務 B 的修改出於好意(想讓公式好懂)。公司應該怎麼規定「誰可以改共用函式、改之前要做什麼」?這和第 1.1 節「誰有權改
MIN_MARGIN」是同一類問題嗎?