| Vocabulary | |
|---|---|
| -Interceptor | 欄截器 |
| ExceptionInterceptor | 例外狀況攔截器 |
| -Aspect | 側面、局面。 |
| LogAspect | 日誌方面，在方法執行的前後加入日誌。 |
| Vocabulary | HTTP Verb | |
|---|---|---|
| Index | GET | 資源的起始頁面 |
| List | GET | 依條件列出資料，若無條件則表示全部。 |
| Details | GET | 取得單筆資料 |
| New | GET | 新增資料用的頁面 |
| Create | POST | 新增資料用的方法 |
| Edit | GET | 編輯資料用的頁面 |
| Save | PATCH | 更新資料用的方法 |
| Destroy | GET | 刪除資料用的頁面 |
| Remove | DELETE | 移除單筆資料，若要依條件刪除資料就實作多載方法。 |
| Login | GET | 登入用的頁面 |
| Authenticate | POST | 驗證使用者所送出的登入資訊 |
| Logout | DELETE | 登出 |
| HTTP Verb | Safe? | Idempotent? |
|---|---|---|
| GET | Y | Y |
| POST | N | N |
| PUT | N | Y |
| PATCH | N | N (or Y) |
| DELETE | N | Y |
*Idempotent: 如果相同的操作再執行第二遍第三遍，結果還是跟第一遍的結果一樣（也就是說不管執行幾次，結果都跟只有執行一次一樣）
- GET
- 名詞資源視為受詞，命名優先使用複數型態，無論使用單數或複數型態，要一致。
EX: /members/123456, /member/123456- 動名詞資源也是一種名詞。
- 不可數名詞無單複數型態，若要表達複數型態，則補充描述。
EX: ❌/feedbacks, ⭕/feedback-list
- PATCH
- 關於 PATCH 的 Non-Idempotent 特性，其實 PATCH 可以是 Idempotent，在這篇 RFC5789 有說明。
以名詞複數呈現或以 -List、-Collection 結尾，底下是遇到的一些特殊案例：
- xxxIds、xxxIDs：表達一個識別值的集合，建議改用 xxxIdentifiers 命名。
Add、Buy、Capture、Decrease、Edit、Find、Finish、Follow、Increase、Insert、Listen、Purchase、Pull、Quote、Reply、Save、Sell、Set、Start、Update、Upload、Vote
| Vocabulary | |
|---|---|
| noun | 名詞 |
| verb | 動詞 |
| plural | 複數 |
| synonym | 同義詞 |
| antonym | 反義詞 |
| abbreviation | 縮寫 |
| Vocabulary |
|---|
| Primary, Secondary, Tertiary, Quaternary, Quinary, Senary, Septenary, Octonary, Nonary, Denary. |
| First, Second, Third, Fourth, Fifth, Sixth, Seventh, Eighth, Ninth, Tenth, Eleventh, Twelfth, Thirteenth, Fourteenth, Fifteenth, Sixteenth, Seventeenth, Eighteenth, Nineteenth, Twentieth. |
| Vocabulary | |
|---|---|
| Verification | 查證；作證。（側重證明） |
| Validation | 批准；驗證。（側重批准） |
| Authentication | 系統判斷使用者是否真的是他宣稱的那個人。（檢查 Id & Password） |
| Authorization | 系統根據該帳號所擁有的權限驗証該使用者。（檢查使用權限） |
| Certification | 發證；檢定。 |
| Vocabulary | |
|---|---|
| dis- | 與某事物分開或是遠離、分離。 |
| un- | 是「不」或是與某事物相反，或是沒有某事物、缺乏某事物、一種遭到剝奪的感覺。 |
| non- | 基本上就是「not」 |
| in-、im-、il-、ir- | 顛倒、相反。 in-、im，不只代表「不」的意思，還有「朝向」或「導致」的意思。 im-：接 b、m、p 開頭的字 il-：接 l 開頭的字 ir-：接 r 開頭的字 |
| mis- | 是「錯誤地...」 |
| Vocabulary | |
|---|---|
| Percent | 百分之(某數字)，一般都是有數字在前面。 |
| Percentage | 百分率，通常用在表達某個什麼的百分率，不會是一個數字。 |
| Rate | 比率、比值，像是稅率、犯罪率、...，通常會有一個數字。 |
| Ratio | 兩個量的比值，其實是強調相比、相除的關係，但是它的兩個量必須在上下文出現。 E.g. 學生及老師比是 35:1。 |
| Proportion | 指比例關係，可代替 Ratio 使用，但是在相比的兩個量在上下文沒有出現是必須用 Proportion 而不能用 Ratio。 E.g. 只有小比例的人口感染 H7N9 病毒。 |
| Vocabulary | |
|---|---|
| Divide | 將一個東西分成兩個或更多 E.g. 我將披薩分成好幾塊。 |
| Separate | 分離多個物體並讓它們遠離彼此。 E.g. 我將兩個孩子分開。 |
| Split | 相對上面兩個，是比較通用的用法。 E.g. 「我將木頭分成兩半。」、「我分開正在打架的兩個人。」 |
| Vocabulary | |
|---|---|
| Failure | 失敗是一種系統內部的意外事件，是意料之外的，會阻止系統繼續正常地運行。 |
| Error | 錯誤是意料之中的，並且針對錯誤的情況進行了處理，將會作為程序的正常處理過程。（例如：在輸入驗證的過程中發現了錯誤，並且回應給客戶端。） |
| Vocabulary | |
|---|---|
| Configure | 動詞，改變可選項的動作。 |
| Settings | 可選項的集合 |
| Options | 可選項 |
| 一句話解釋以上三者的關係「Configure some options in the settings.」 | |
| Configuration | 已確定 Configure 的結果 |
| Config | Configure 或 Configuration 的縮寫 |
| Profile | 指一系列對特定個體的不一定全面的描述，翻成輪廓更准確。 |
| Preferences | 偏好、喜好。 |
| Vocabulary | |
|---|---|
| Options | We have set some things already, and give you the option to change them. |
| Settings | View or modify the list of things that can be set |
| Properties | Change one or more properties of this item |
| Configuration | We have defaults, but they're so barebones you probably want to configure it yourself. |
| Preferences | Tell us how you prefer this to work |
| Vocabulary | |
|---|---|
| Simulator | 著重於整體模型的建造 |
| Emulator | 著重於主要功能的實踐 |
| 一句話來解釋這兩者的差異「If a flight-simulator could transport you from A to B then it would be a flight-emulator.（如果一個飛行模擬器能將你從 A 傳送到 B，那麼它就是飛行仿真器。）」 |
| Vocabulary | |
|---|---|
| Before / After | 大於（>）/ 小於（<） |
| Start / End | 大於等於（>=）/ 小於等於（<=） |
用 ASP.NET Core MVC 開發，會把畫面跟 Web API 混在同一個專案裡面，這邊列一些命名慣例來作為參考。
以某網站的某個頻道為例，假設這個頻道叫 Laojiao，Laojiao 底下有 Project，Project 底下有 Article，Article 底下有 Comment，Comment 底下有 Reply，擁有五層的階層關係，但是 Laojiao 是抽象的概念，沒有實體資料，有實體資料是從 Project 開始，所以實體階段關係只有四層，如果以 ASP.NET Core MVC 專案範本進行開發，Web API 的設計規劃會是怎樣？
原則：在 API 的網址中，如果有 Action 參數，應該加到網址中。
例如：/laojiao/project?projectId=1，應該改為 /laojiao/project/1。
| Web API | Area | Controller | Action | 應用場景 | |
|---|---|---|---|---|---|
| 畫面 | HttPGet /laojiao | Laojiao | Project | Index |
| Web API | Area | Controller | Action | 應用場景 | |
|---|---|---|---|---|---|
| 畫面 | HttpGet /laojiao/project/{projectId:int} | Laojiao | Project | Project | |
| 公開資料 | HttpGet /laojiao/project/{projectId:int}/info | Laojiao | Project | Info | 部分的資料，通常是無需權限即可存取。 |
| 詳細資料 | HttpGet /laojiao/project/{projectId:int}/details | Laojiao | Project | Details | 完整的資料，有時候需要權限才能存取。 |
| 專案留言列表 | HttpGet /laojiao/project/{projectId:int}/comment/list | Laojiao | Comment | List | 能存取文章時，留言連同回覆一併存取。 |
| Web API | Area | Controller | Action | 應用場景 | |
|---|---|---|---|---|---|
| 畫面 | HttpGet /laojiao/project/{projectId:int}/article | Laojiao | Article | Index | |
| 資料 | HttpGet /laojiao/project/{projectId:int}/article/list | Laojiao | Article | List |
| Web API | Area | Controller | Action | 應用場景 | |
|---|---|---|---|---|---|
| 畫面 | HttpGet /laojiao/project/{projectId:int}/article/{articleId:int} | Laojiao | Article | Article | |
| 公開資料 | HttpGet /laojiao/project/{projectId:int}/article/{articleId:int}/info | Laojiao | Article | Info | 部分的資料，通常是無需權限即可存取。 |
| 詳細資料 | HttpGet /laojiao/project/{projectId:int}/article/{articleId:int}/details | Laojiao | Article | Details | 完整的資料，有時候需要權限才能存取。 |
| 文章留言列表 | HttpGet /laojiao/project/{projectId:int}/article/{articleId:int}/comment/list | Laojiao | ArticleComment | List | 能存取文章時，留言連同回覆一併存取。 |
| Web API | Area | Controller | Action | 應用場景 | |
|---|---|---|---|---|---|
| 畫面 | HttpGet /laojiao/project/{projectId:int}/article/{articleId:int}/comment/{commentId:int} | Laojiao | ArticleComment | Comment |
| Web API | Area | Controller | Action | 應用場景 | |
|---|---|---|---|---|---|
| 回覆列表 | HttpGet /laojiao/project/{projectId:int}/article/{articleId:int}/comment/{commentId:int}/reply/list | Laojiao | ArticleCommentReply | List | |
| ArticleComment | ReplyList | ||||
| 單篇回覆 | HttpGet /laojiao/project/{projectId:int}/article/{articleId:int}/comment/{commentId:int}/reply/{replyId:int}/details | Laojiao | ArticleCommentReply | Details | |
| ArticleComment | ReplyDetails |
| Web API | Area | Controller | Action | 應用場景 | |
|---|---|---|---|---|---|
| 畫面 | HttpGet /laojiao/project/{projectId:int}/article/new | Laojiao | Article | New | |
| 新增 | HTTP POST /project/{projectId:int}/article | Project | Article | Create |
| Web API | Area | Controller | Action | 應用場景 | |
|---|---|---|---|---|---|
| 畫面 | HttpGet /laojiao/project/{projectId:int}/article/edit | Laojiao | Article | Edit | |
| 儲存 | HttpPatch /project/{projectId:int}/article | Project | Article | Save | |
| 儲存 | HttpPut /project/{projectId:int}/article | Project | Article | Save |
| Web API | Area | Controller | Action | 應用場景 | |
|---|---|---|---|---|---|
| 刪除 | HttpDelete /project/{projectId:int}/article/{articleId:int} | Project | Article | Remove |
| Web API | Area | Controller | Action | 應用場景 | |
|---|---|---|---|---|---|
| 刪除 | HttpDelete /project/{projectId:int}/article?id=1&id=2&id=3 | Project | Article | Remove |
| 動作 | 命名格式 | 命名範例 | 適用情境 | |
|---|---|---|---|---|
| Create | CreateXXXInput | CreateAccountInput CreateArticleInput |
明確代表是新增資料（不涉及更新） | |
| Create / Update | SaveXXXInput | SaveUserProfileInput SavePhotographyPreferencesInput |
用於新增或更新都可能的情境（多數一般表單） | |
| Update | UpdateXXXInput | UpdateUserProfileInput UpdatePhotographyPreferencesInput |
明確代表是更新資料（不涉及新增） | |
| Read (List) | XXXListFilter | ArticleListFilter UserListFilter |
針對列表查詢提供過濾條件（回傳部分資料的清單） | |
| Read (複數資源) | XXXFilter (複數) | ArticlesFilter MembersFilter |
若資源本身語意為集合或明確強調複數 | |
| Remove | RemoveXXXCommand | RemoveAccountCommand RemoveArticleCommand |
用於需要傳遞刪除參數的 API（例如：POST /remove、DELETE /{id}） |
| 動作 | 命名範例 | 說明 |
|---|---|---|
| edit | editExif | 進入編輯狀態 |
| add | addExif | 新增 |
| store | storeExif | 儲存 |
| discard | discardExif | 刪除 |
| revert | revertExif | 取消 |