README
¶
Golang 客戶端
Mego 已附帶了 Golang 客戶端，可供你在後端與伺服端的 Mego 進行溝通或是單元測試。
索引
連線
透過 MegoClient 類別建立一個到伺服器的 Mego 連線。在另一個參數可夾帶客戶端資料，這令你不需要每次發送資料都須額外參夾使用者資料。
// 建立一個新的 Mego 客戶端，並經由 WebSocket 溝通。
ws := client.NewClient("ws://localhost/").
// 透過 `Set` 保存本客戶端的資料至遠端，
// 如此一來就不需要每次都發送相同重複資料。
Set(client.H{
"Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
"Version": "1.0",
})
if err := ws.Connect(); err != nil {
panic(err)
}
重啟連線
透過 Reconnect 重啟一個新的連線。
ws.Reconnect()
斷開連線
透過 Close 結束到伺服器的連線。
ws.Close()
呼叫伺服端
透過 Call 可以呼叫伺服端並執行指定方法，且取得相關結果。
設置酬載
透過 Send 在呼叫遠端方法之前設置欲傳遞資料，完成後以 End 來真正地發送請求。倘若傳入的資料是一個陣列則會被當作參數對待，伺服端可以更加快速地使用該資料。
如果傳入的資料是物件，伺服端則能以更有條理的方式處理資料但稍微複雜了些。傳入的資料如果是字串則會被當作 JSON 看待。
var resp Response
// 呼叫遠端的 `Sum` 方法，並傳入兩個參數。
err := ws.Call("Sum").
Send([]int{5, 3}).
End()
// 呼叫遠端的 `Sum` 方法，並傳入一個物件。
err = ws.Call("Sum").
Send(client.H{
"NumberA": 5,
}).
End()
送出資料
設置資料時並不會直接送出請求，需透過 End 才能發送已設置好的資料請求。
var resp Response
// 呼叫遠端的 `Sum` 方法，並傳入兩個參數。
err := ws.Call("Sum").
Send([]int{5, 3}).
End()
以 EndStruct 則可以將設置好的資料送出並將接收到的回應映射到本地端的建構體。
var resp Response
// 呼叫遠端的 `Sum` 方法，並傳入兩個參數。
// 且將接收到的資料映射到 `Response` 建構體。
err := ws.Call("Sum").
Send([]int{5, 3}).
EndStruct(&resp)
檔案上傳
透過 SendFile 上傳檔案至伺服端，此用法非常彈性。
透過檔案路徑
當 SendFile 的第一個參數是 string 型態時會被當作檔案路徑看待。Mego 客戶端會自動讀取該路徑的檔案二進制內容與其檔案名稱並上傳至伺服端。
// 呼叫遠端的 `Upload` 方法。
err := ws.Call("Upload").
// 並且傳遞下列物件資料。
Send(client.H{
"AlbumID": 30,
}).
// 且夾帶名為 `photo.png` 的檔案。
SendFile("./photo.png").
End()
透過 *os.File
Mego 客戶端能在 SendFile 的第一個參數是 *os.File 時自動讀取其內容，並且取得該檔案名稱一同上傳至遠端。
// 開啟一個檔案並取得其 *os.File 資料。
file, _ := os.Open("video.mp4")
// 呼叫遠端的 `Upload` 方法。
err := ws.Call("Upload").
// 並且傳遞下列物件資料。
Send(client.H{
"AlbumID": 30,
}).
// 以 *os.File 方式夾帶名為 `video.mp4` 的檔案。
SendFile(file).
End()
透過二進制
你亦能直接傳入二進制內容至 SendFile 的第一個參數，需注意的是 Mego 客戶端將無法取得檔案的名稱，因此在伺服端會接收到一個空白的檔案名稱。
// 開啟一個檔案並取得其二進制資料。
path, _ := filepath.Abs("./textfile.txt")
bytes, _ := ioutil.ReadFile(path)
// 呼叫遠端的 `Upload` 方法。
err := ws.Call("Upload").
// 並且傳遞下列物件資料。
Send(client.H{
"Author": "YamiOdymel",
}).
// 以二進制方式夾帶並上傳 `textfile.txt` 的內容。
SendFile(bytes).
End()
自訂欄位名稱
上傳檔案時 Mego 客戶端會自動以 File1、File2、File3 等遞加方式替檔案欄位進行命名。如果你想要手動指定檔案欄位名稱，請在 SendFile 的第二個參數指派。
// 呼叫遠端的 `Upload` 方法。
err := ws.Call("Upload").
// 這個檔案欄位會被命名為 `File1`。
SendFile(file).
// 這個檔案欄位會被命名為 `TextFile`。
SendFile(bytes, "TextFile").
// 這個檔案欄位會被命名為 `File2`。
SendFile(anotherFile).
End()
區塊上傳
透過 SendFileChunks 將一個大型檔案以區塊的方式上傳至遠端伺服器。和 SendFile 一樣的是你可以傳入 []byte、string、*os.File 的型態資料到第一個參數。
有個需要注意的地方：使用區塊上傳時僅能夾帶一個檔案，且不可與其他 SendFile 並用。
// 呼叫遠端的 `Upload` 方法。
err := ws.Call("Upload").
// 並且傳遞下列物件資料。
Send(client.H{
"AlbumID": 30,
}).
// 這個檔案欄位會被命名為 `File1`。
SendFileChunks("./largeFile.zip").
End()
錯誤處理
err := ws.Call("Sum").
Send([]int{5, 3}).
End()
if err != nil {
}
事件監聽
基本的內建事件有 Open（連線）, Close（連線關閉）, Reopen（重新連線）, Message（收到資料）, Error（錯誤、斷線）可供監聽。
ws.On("Open", func() {
fmt.Println("成功連線！")
})
移除監聽器
透過 Off 可以移除先前新增的監聽函式，但這仍會接收到來自伺服端的事件。欲要完全終止請使用 Unsubscribe。
ws.Off("Open")
訂閱自訂事件
透過 Subscribe 告訴遠端伺服器我們要訂閱自訂事件與指定頻道，並透過 On 處理接收到的事件。一個事件可以有很多個頻道，類似一個「新訊息」事件來自很多個聊天室。
// 先告訴伺服器我們要訂閱 `NewMessage` 事件，且表明這是頻道 `Chatroom1`。
// 指定頻道可以避免接收到其他人的事件。
err := ws.Subscribe("NewMessage", "Chatroom1")
if err != nil {
panic(err)
}
// 當接收到 `NewMessage` 事件時所執行的處理函式。
ws.On("NewMessage", func(e *client.Event) {
fmt.Println("收到 newMessage 事件！")
})
取消訂閱
透過 Unsubscribe 將自己從遠端伺服器上的指定事件監聽列表中移除，這將會停止接收到之後的事件。
err := ws.Unsubscribe("NewMessage", "Chatroom1")
Documentation
¶
Index ¶
- Constants
- Variables
- type Client
- func (c *Client) Call(method string) *Request
- func (c *Client) Close() error
- func (c *Client) Connect() error
- func (c *Client) Off(event string) *Client
- func (c *Client) On(event string, handler func(*Event)) *Client
- func (c *Client) Reconnect() error
- func (c *Client) Set(data map[string]interface{}) *Client
- func (c *Client) Subscribe(event string, channel string) error
- func (c *Client) Unsubscribe(event string, channel string) error
- type Error
- type Event
- type File
- type H
- type Option
- type Request
- func (r *Request) End() error
- func (r *Request) EndStruct(dest interface{}) error
- func (r *Request) Send(data interface{}) *Request
- func (r *Request) SendFile(file interface{}, fieldName ...string) *Request
- func (r *Request) SendFileChunks(file interface{}, fieldName ...string) *Request
- func (r *Request) SendFiles(files []interface{}, fieldName ...string) *Request
- type RequestOption
- type Response
Constants ¶
View Source
const ( // StatusError 表示有內部錯誤發生。 StatusError = -1000 // StatusFull 表示此請求無法被接受，因為額度已滿。例如：使用者加入了一個已滿的聊天室、好友清單已滿。 StatusFull = -1001 // StatusExists 表示請求的事物已經存在，例如：重複的使用者名稱、電子郵件地址。 StatusExists = -1002 // StatusInvalid 表示此請求格式不正確。 StatusInvalid = -1003 // StatusNotFound 表示找不到請求的資源。 StatusNotFound = -1004 // StatusNotAuthorized 表示使用者需要登入才能進行此請求。 StatusNotAuthorized = -1005 // StatusNoPermission 表示使用者已登入但沒有相關權限執行此請求。 StatusNoPermission = -1006 // StatusUnimplemented 表示此功能尚未實作完成。 StatusUnimplemented = -1007 // StatusTooManyRequests 表示使用者近期發送太多請求，需稍後再試。 StatusTooManyRequests = -1008 // StatusResourceExhausted 表示使用者可用的額度已耗盡。 StatusResourceExhausted = -1009 // StatusBusy 表示伺服器正繁忙無法進行執行請求。 StatusBusy = -1010 // StatusFileRetry 表示檔案區塊發生錯誤，需要重新上傳相同區塊。 StatusFileRetry = -1011 // StatusFileEmpty 表示上傳的檔案、區塊是空的。 StatusFileEmpty = -1012 // StatusFileTooLarge 表示檔案過大無法上傳。 StatusFileTooLarge = -1013 // StatusTimeout 表示這個請求費時過久導致逾期而被終止。 StatusTimeout = -1014 )
Variables ¶
View Source
var ( // ChunkSize 是預設的區塊分切基準位元組大小。 ChunkSize = mego.MB * 1 // Timeout 是預設的逾期秒數。 Timeout = time.Second * 15 // UploadTimeout 是每個區塊、所有檔案的上傳逾期秒數，`0` 表示無上限。 UploadTimeout = time.Second * 30 )
View Source
var ( // ErrChunkWithFiles 表示不能上傳區塊檔案同時夾帶其他檔案實體。 ErrChunkWithFiles = errors.New("mego: cannot send the file chunks with the file entities") // ErrTimeout 表示一個請求過久都沒有回應。 ErrTimeout = errors.New("mego: request timeout") // ErrClosed 表示正在使用一個已經關閉的連線。 ErrClosed = errors.New("mego: use of closed connection") // ErrSent 表示正在使用一個早已發送出去的請求。 ErrSent = errors.New("mego: use of sent request") // ErrSubscriptionRefused 表示欲訂閱的事件請求被拒。 ErrSubscriptionRefused = errors.New("mego: the event subscription was refused") // ErrAborted 表示請求已被終止。 ErrAborted = errors.New("mego: the request has been aborted") // ErrEmptyRequest 表示欲發送的請求是個 `nil`。 ErrEmptyRequest = errors.New("mego: the request is empty") )
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// URL 是遠端 Mego 伺服器的網址。
URL string
// UUID 是此客戶端的獨立編號。
UUID string
// Option 是這個客戶端的設置選項。
Option *Option
// contains filtered or unexported fields
}
Client 是一個客戶z端。
func (*Client) Set ¶
Set 能夠將指定資料保存於遠端伺服器，避免每次請求都需傳遞相同資料供伺服端讀取。 由於資料保存在指定伺服器上，若使用負載平衡可能導致另一個伺服器找不到相關資料，因此使用負載平衡時請不要用上此方式。
type Error ¶
type Error struct {
// Code 是錯誤代號。
Code int `codec:"c" msgpack:"c"`
// Message 是人類可讀的簡略錯誤訊息。
Message string `codec:"m" msgpack:"m"`
// Data 是錯誤的詳細資料。基於 Message Pack 格式需要透過 `Bind` 映射到本地建構體。
Data []byte `codec:"d" msgpack:"d"`
}
Error 呈現了一個遠端所傳回的錯誤。
type Event ¶
type Event struct {
// Data 是事件所夾帶的資料。基於 Message Pack 格式需要透過 `Bind` 映射到本地建構體。
Data []byte
}
Event 呈現了一個接收到的事件。
type File ¶
type File struct {
// Binary 是檔案的二進制。
Binary []byte `codec:"b" msgpack:"b"`
// ID 是檔案編號，用於區塊組合。
ID int `codec:"i" msgpack:"i"`
// Parts 呈現區塊的分塊進度。索引 0 表示總共區塊數，索引 1 則是本區塊編號。
// 如果這個切片是空的表示此為實體檔案而非區塊。
Parts []int `codec:"p" msgpack:"p"`
// Name 是檔案的原始名稱。
Name string `codec:"n" msgpack:"n"`
// contains filtered or unexported fields
}
File 呈現了一個欲上傳的檔案資料。
type Option ¶
type Option struct {
// ChunkSize 是預設的區塊分切基準位元組大小。
ChunkSize int
// Timeout 是預設的逾期秒數。
Timeout time.Duration
// UploadTimeout 是每個區塊、所有檔案的上傳逾期秒數，`0` 表示無上限。
UploadTimeout time.Duration
}
Option 呈現了一個客戶端的設置。
type Request ¶
type Request struct {
// Method 是欲呼叫的方法名稱。
Method string `codec:"m" msgpack:"m"`
// Params 是資料或參數。
Params interface{} `codec:"p" msgpack:"p"`
// Files 是此請求所包含的檔案欄位與其內容。
Files map[string][]*File `codec:"f" msgpack:"f"`
// ID 為本次請求編號，若無則為單次通知廣播不需回應。
ID int `codec:"i" msgpack:"i"`
// Option 是這個請求的選項設置。
Option *RequestOption
// contains filtered or unexported fields
}
Request 呈現了一個籲發送至遠端伺服器的請求。
func (*Request) SendFileChunks ¶
SendFileChunks 會保存稍後將以區塊方式上傳的檔案。 注意：請求使用區塊檔案上傳時，不可使用 `SendFile` 夾帶其他檔案。
type RequestOption ¶
type RequestOption struct {
// ChunkSize 是此請求區塊分切基準位元組大小，會取代原先的客戶端設置。
ChunkSize int
// Timeout 是此請求逾期的秒數，會取代原先的客戶端設置。
Timeout time.Duration
// UploadTimeout 是每個區塊、所有檔案的上傳逾期秒數，`0` 表示無上限，會取代原先的客戶端設置。
UploadTimeout time.Duration
}
RequestOption 呈現了一個請求的設置。
type Response ¶
type Response struct {
// Event 是欲呼叫的客戶端事件名稱。
Event string `codec:"v" msgpack:"v"`
// Result 是正常回應時的資料酬載。
Result interface{} `codec:"r" msgpack:"r"`
// Error 是錯誤回應時的資料酬載，與 Result 兩者擇其一，不會同時使用。
Error Error `codec:"e" msgpack:"e"`
// ID 是當時發送此請求的編號，用以讓客戶端比對是哪個請求所造成的回應。
ID int `codec:"i" msgpack:"i"`
}
Source Files
Click to show internal directories.
Click to hide internal directories.