Skip to content

Latest commit

 

History

History
125 lines (100 loc) · 4.04 KB

README-chinese.md

File metadata and controls

125 lines (100 loc) · 4.04 KB

如何給自己的Golang軟件�加配標註文件

��一下內容主要圍繞源代碼範本 - github進行講解

從當地文件開始

Godoc

一個由Golang社區提供的，�非常便利的一個工具。它能幫助�你很快得生成一個屬於你私人的golang特色的參考文件，你只需要:

godoc -http=:6060

之後便能生成$GOPATH路徑下的所有文檔，可以由一下開啟

open http://localhost:6060/pkg

當然，文件的備註需要由你自行提供。備註來源自源代碼周圍的旁白，按這裡可以看到相應的文法和小技巧

由此可見，以上步驟可以生成$GOPATH下，所有子文件檔案的註解，�但其實很大部分都是沒有必要的

自動化 - Docker

Dockerfile

# 使用Golang官方運行端
FROM golang:1.10.3

# 環境變數的使用，增加可重用性
ENV APP_NAME=godoc-example
ENV WORKING_DIR=$GOPATH/src/github.com/marvin5064/$APP_NAME

# 設置Golang的工作路徑
WORKDIR $WORKING_DIR

# 將所有本地文件加配到Docker容器裡
ADD . .

CMD godoc -http=:6060

安裝及運行

docker build . \
    -t godoc-example/v1 # giving a tag for reference
docker run \
    -p 6060:6060 \ # (local):(docker) as we expose 6060 port in docker
    -it godoc-example/v1 # run for a built image by tag

以簡單�操作，所以指令均被壓縮在 Makefile中, 你可以直接輸入指令 make docker-run以執行以上步驟

接收成果

經由以上步驟，我們可以簡單生成所有Golang官方註解文件，以及�軟件相�關文件

open http://localhost:6060/pkg
open http://localhost:6060/pkg/github.com/marvin5064/godoc-example/

加強版

我們其實可以進一步將Golang官方文件給省略掉

經過一番查證，godoc暫時不支持獨立文件的註解檔案，�這裏需要一些小技巧，如下:

  1. 運用wget / curl生成獨立的相關文件註解檔，腳本如下:�
#!/bin/bash
CURRENT_PKG=`go list -e`

# 啟動godoc主機
godoc -http=:6060 & DOC_PID=$!

# 等待godoc主機服務器成功運行
until curl -sSf "http://localhost:6060/pkg/$CURRENT_PKG/" > /dev/null
do
    sleep 1
done
sleep 1

# 遞歸式的抓包整個�網頁文件，包括 HTML/CSS/JS
# 關閉robots check, 不然將可能因為其他安全原因阻止抓包，原因會被列在`robots.txt`文件中
# 之需要抓取需要的文件，省去不必要的
wget -r -p \
    -e robots=off \
    --include-directories="/lib/godoc,/pkg/$CURRENT_PKG,/src/$CURRENT_PKG" \
    --exclude-directories="/pkg/$CURRENT_PKG/vendor,/src/$CURRENT_PKG/vendor" \
    "http://localhost:6060/pkg/$CURRENT_PKG/"

# 停止godoc主機
kill -9 $DOC_PID

# 文件會被生成在 `localhost:6060`文件檔中, 我們需要將他們移出Docker容器，並在自己的電腦中使用
mv localhost:6060 /tmp

同樣，Makefile 已經備份的快捷指令

make docker-gen-docs
  1. 將靜態網頁文件以網絡服務器的形式，運行出去(省略http server部分)
make docker-gen-docs-server
  1. 最後
open http://localhost:8080/pkg/github.com/marvin5064/godoc-example/

Reference

總結

改善點

  • 使用 NGINX 代替nodejs�的網頁服務器
    • NGINX 用做靜態網頁服務器，一流
    • 主導系統安全，網絡連結管理。不需要在軟體的層面著手
  • 使用 docker-compose
    • 可以使用一個容器，同時處理文件生成，和文件服務端
    • 如果使用 CD/CI 工序, 不同容器作不同功效
  • 加強版缺點太多
    • 等待Golang社區改善
    • 文件生成依靠簡單的網絡�爬蟲，漏洞比較容易出現
    • 三方�依賴文件註解缺失
      • 如果��軟件本身使用�三方�依賴文件(vendor)，建議�使用docker，�將vendor的所有文件移動到$GOPATH/src之後再生成所有文件