原文地址： https://cwiki.apache.org/confluence/display/CLOUDSTACK/CloudStack+API+Coding+Guidelines

前言

本文闡述為CloudStack編寫新API或者更新已存在API時(shí)應(yīng)遵循的約定和編程指引。

參考文檔

?（暫略）

介紹

當(dāng)你需要為CS添加新的API時(shí)，需要?jiǎng)?chuàng)建一個(gè)Request類和Response類（或者在擴(kuò)展CS API功能時(shí)它的API Responese已經(jīng)定義的情況下重用已經(jīng)存在的API Response類）。

編寫CS API Request類

1、request繼承自*Cmd抽象類

CUD（新增/更新/刪除 命令）

R（讀取列表）命令

?

重要- 從2.x開始，新的CUD API命令不再繼承自 BaseCmd 類，它們被看做是異步命令，繼承自 BaseAsyncCmd或者 BaseAsyncCreateCmd。

? ? ? ?擴(kuò)展BaseAsyncCmd或者BaseAsyncCreateCmd，創(chuàng)建新的CS實(shí)體命令擴(kuò)展BaseAsyncCreateCmd，UD命令擴(kuò)展BaseAsyncCmd。

2、新添加的command類應(yīng)以“*Cmd”結(jié)尾且標(biāo)注 @ApiCommand。更多請(qǐng)閱參考文檔 ? Annotations use in the API 中的 @ parameters。

3、定義所有的請(qǐng)求參數(shù)，且所有的都用@Parameter標(biāo)注。

4、為RUD命令實(shí)現(xiàn)execute()方法，為R命令實(shí)現(xiàn) execute()/create()。

5、增加s_name--響應(yīng)的名字，并且為小寫。

6、在為命令命名時(shí)，根據(jù)含義優(yōu)先使用 create/delete/update/list，只有當(dāng)這些前綴不能滿足你的邏輯時(shí)才考慮用你自己的（如assign）。

編寫CS API Response類

?1、讓你的類繼承自 BaseResponse。

?2、用 @EntityReference標(biāo)注Response類，并設(shè)定關(guān)聯(lián)的CloudStack接口，它是你返回給API用戶的對(duì)象。比如 VolumeResponse 用 EntityReference 標(biāo)注關(guān)聯(lián)Volume接口。

?3、將每個(gè)參數(shù)用 @SerializedName 和?@Param注解。?請(qǐng)閱在 Annotations use in the API 中關(guān)于這些注解的細(xì)節(jié)。

?4、參數(shù)名稱都是小寫。

?5、確保沒有將真實(shí)的DB id設(shè)置到id字段將其暴漏，請(qǐng)用 UUID值代替。

API位置和注冊(cè)

命令的位置取決于該命令將是可用/禁用插件或者CloudStack核心的一部分。

當(dāng)命令是CS核心的一部分

• 位置：Reque/Response代碼放在 cloud-api/cloud-engine-api下。
• 訪問權(quán)限：命令的訪問控制權(quán)限（誰有能調(diào)用它）在 commands.properties.in里注冊(cè)。
• 命令注冊(cè)：命令應(yīng)添加到CS支持的所有的API列表中，該列表由 ManagementServerImpl.? getCommands()獲得

注意當(dāng)命令調(diào)用完成時(shí)，它們關(guān)聯(lián)的只能是 cloud-api 或 cloud-util包里的接口

?

當(dāng)命令是插件/服務(wù)的一部分

• 位置：Reque/Response代碼放在plugin包下。
• 訪問權(quán)限：在Cmd文件里定義權(quán)限，使用 @APICommand 注解 "authorized"字段，如 authorized = {RoleType.Admin}) 。
• 命令注冊(cè)：讓插件管理類繼承自 PluggableService 接口，增加到命令列表的命令由getCommands()返回。

定義在插件中的命令只關(guān)聯(lián)位于 cloud-api/cloud-utils/<your plugin>中的接口。

?

修改已存在API的規(guī)則

1、對(duì)Request：不要將參數(shù)從可選改為必需的；

2、對(duì)Request：不要在已存在的命令里增加一個(gè) required=true的參數(shù)；

3、對(duì)Request：不要降低command的權(quán)限，從對(duì)普通用戶可用降到只對(duì)管理員可用；

4、對(duì)Request/Response：不要重命名已有的參數(shù)；

5、對(duì)Request/Response：不要更改參數(shù)的類型（如從String改為Map）

6、對(duì)Response：不要?jiǎng)h除Response的參數(shù)，由于第三方軟件會(huì)依賴它。

其它規(guī)則：

1、當(dāng)新增一個(gè)參數(shù)時(shí)，應(yīng)該在它的 ?@Parameter 里標(biāo)注 "since=release #" 字段；

2、如果你認(rèn)為有些參數(shù)會(huì)在未來被刪除掉，請(qǐng)標(biāo)注 @Deprecated，并確保在第n版本里記錄。當(dāng)它發(fā)布后，客戶有機(jī)會(huì)去檢查/修改代碼以去掉這個(gè)參數(shù)。于是可以在第n+1個(gè)版本去除該參數(shù)。

?

CloudStack API編程指引