add doc (#181)

docs/get-started.rst

@@ -0,0 +1,8 @@
+Get started
+======================================
+
+.. toctree::
+   :maxdepth: 4
+   :glob:
+
+   getstarted/*

docs/getstarted/install.md

@@ -0,0 +1,13 @@
+最小化安装
+=====
+1. Go 参照官方文档安装1.8+版本 https://golang.org/doc/install
+2. 执行命令 git clone git@github.com:ServiceComb/go-chassis.git
+3. 执行命令 go get -u github.com/FiloSottile/gvt
+4. 进入go-chassis目录执行gvt restore
+5. 请参考文档安装Service center https://github.com/ServiceComb/service-center/releases
+
+使用RPC通信
+===================
+安装protobuff 3.2.0 https://github.com/google/protobuf
+
+安装golang插件 https://github.com/golang/protobuf

docs/getstarted/writing-rest.md

@@ -0,0 +1,110 @@
+Writing Rest service
+==========================
+服务端
+1个工程或者go package，推荐结构如下
+
+server/
+
+├── conf
+
+│ ├── chassis.yaml
+
+│ └── microservice.yaml
+
+└── main.go
+
+1.编写接口
+```go
+type RestFulHello struct {}
+
+func (r *RestFulHello) Sayhello(b *restful.Context) {
+    b.Write([]byte("get user id: " + b.ReadPathParameter("userid")))
+}
+```
+2.注册路由
+```go
+func (s *RestFulHello) URLPatterns() []restful.Route {
+    return []restful.Route{
+        {http.MethodGet, "/sayhello/{userid}", "Sayhello"},
+    }
+}
+```
+3.注册接口
+
+第一个参数表示你要向哪个协议注册，第三个为schema ID,会在调用中使用
+
+chassis.RegisterSchema("rest", &RestFulHello{}, server.WithSchemaId("RestHelloService"))
+说明:
+
+想注册的rest协议的接口，必须实现URLPatterns方法定义路由
+路由中暴露为API的方法都要入参均为*restful.Context
+3.修改配置文件chassis.yaml
+```yaml
+cse:
+  service:
+    registry:
+      address: http://127.0.0.1:30100
+  protocols:
+    rest:
+      listenAddress: 127.0.0.1:5001
+```
+4.修改microservice.yaml
+```yaml
+service_description:
+  name: RESTServer
+```
+5.main.go中启动服务
+```go
+func main() {
+    //start all server you register in server/schemas.
+    if err := chassis.Init(); err != nil {
+        lager.Logger.Error("Init failed.", err)
+        return
+    }
+    chassis.Run()
+}
+```
+客户端
+1个工程或者go package，推荐结构如下
+
+client/
+
+├── conf
+
+│ ├── chassis.yaml
+
+│ └── microservice.yaml
+
+└── main.go
+
+1.修改配置文件chassis.yaml
+```yaml
+cse:
+  service:
+    registry:
+      address: http://127.0.0.1:30100
+```
+2.修改microservice.yaml
+
+service_description:
+  name: RESTClient
+3.main中调用服务端，请求包括服务名，schema，operation及参数
+```go
+//if you use go run main.go instead of binary run, plz export CHASSIS_HOME=/path/to/conf/folder
+func main() {
+    //Init framework
+    if err := chassis.Init(); err != nil {
+        lager.Logger.Error("Init failed.", err)
+        return
+    }
+    req, _ := rest.NewRequest("GET", "cse://RESTServer/sayhello/world")
+    defer req.Close()
+    resp, err := core.NewRestInvoker().ContextDo(context.TODO(), req)
+    if err != nil {
+        lager.Logger.Error("error", err)
+        return
+    }
+    defer resp.Close()
+    lager.Logger.Info(string(resp.ReadBody()))
+}
+```

docs/getstarted/writing-rpc.md

@@ -0,0 +1,152 @@
+Writing RPC service
+==========================================
+定义请求与返回结构体
+1个工程或者go package，推荐结构如下
+
+schemas
+
+├── helloworld
+
+│ ├──helloworld.proto
+
+1.定义helloworld.proto文件
+```proto
+syntax = "proto3";
+
+package helloworld;
+
+
+// The request message containing the user's name.
+message HelloRequest {
+  string name = 1;
+}
+
+// The response message containing the greetings
+message HelloReply {
+  string message = 1;
+}
+```
+2.通过pb生成go文件 helloworld.pb.go
+
+protoc --go_out=. hello.proto
+将生成的go文件拷贝到目录中
+
+schemas
+
+├── helloworld
+
+│ ├──helloworld.proto
+
+│ └──helloworld.pb.go
+
+服务端
+1个工程或者go package，推荐结构如下
+
+server/
+
+├── conf
+
+│ ├── chassis.yaml
+
+│ └── microservice.yaml
+
+└── main.go
+
+1.编写接口
+```go
+type HelloServer struct {
+}
+func (s *HelloServer) SayHello(ctx context.Context, in *helloworld.HelloRequest) (*helloworld.HelloReply, error) {
+    return &helloworld.HelloReply{Message: "Go Hello  " + in.Name}, nil
+}
+```
+2.注册接口
+
+第一个参数表示你要向哪个协议注册，第三个为schema ID,会在调用中使用
+
+chassis.RegisterSchema("highway", &HelloServer{}, server.WithSchemaId("HelloService"))
+说明:
+
+想暴露为API的方法都要符合以下条件
+
+第一个参数为context.Context
+
+第二个参数必须是结构体指针
+
+返回的第一个必须是结构体指针
+
+返回的第二个为error
+
+3.修改配置文件chassis.yaml
+```yaml
+cse:
+  service:
+    registry:
+      address: http://127.0.0.1:30100
+  protocols:
+    highway:
+      listenAddress: 127.0.0.1:5000
+```
+4.修改microservice.yaml
+```yaml
+service_description:
+  name: Server
+```
+5.main.go中启动服务
+```go
+func main() {
+    //start all server you register in server/schemas.
+    if err := chassis.Init(); err != nil {
+        lager.Logger.Error("Init failed.", err)
+        return
+    }
+    chassis.Run()
+}
+```
+客户端
+1个工程或者go package，推荐结构如下
+
+client/
+
+├── conf
+
+│ ├── chassis.yaml
+
+│ └── microservice.yaml
+
+└── main.go
+
+1.拿到pb文件生成go代码
+
+protoc --go_out=. hello.proto
+2.修改配置文件chassis.yaml
+
+```yaml
+cse:
+  service:
+    registry:
+      address: http://127.0.0.1:30100
+```
+3.修改microservice.yaml
+```yaml
+service_description:
+  name: Client
+```
+4.main中调用服务端，指定微服务名，schema，operation与参数和返回
+```go
+//if you use go run main.go instead of binary run, plz export CHASSIS_HOME=/path/to/conf/folder
+func main() {
+    //Init framework
+    if err := chassis.Init(); err != nil {
+        lager.Logger.Error("Init failed.", err)
+        return
+    }
+    //declare reply struct
+    reply := &helloworld.HelloReply{}
+    //Invoke with microservice name, schema ID and operation ID
+    if err := core.NewRPCInvoker().Invoke(context.Background(), "Server", "HelloService", "SayHello", &helloworld.HelloRequest{Name: "Peter"}, reply); err != nil {
+        lager.Logger.Error("error", err)
+    }
+    lager.Logger.Info(reply.Message)
+}
+```

docs/index.rst

@@ -5,16 +5,19 @@
 
 Welcome to go-chassis's documentation!
 ======================================
+.. toctree::
+   :maxdepth: 4
+   :caption: User Documentations
+   :glob:
+
+   intro
+   get-started
+   user-guides
+
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
-
+   :caption: Developer Documentations
 
 
-Indices and tables
-==================
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`

docs/intro.rst

@@ -0,0 +1,9 @@
+Introductions
+======================================
+
+.. toctree::
+   :maxdepth: 4
+   :glob:
+
+   intro/*
+

docs/intro/concepts.rst

@@ -0,0 +1,13 @@
+Concepts
+===================
+Registry
+注册中心负责微服务的注册和发现
+
+Registrator
+自注册组件，go-chassis在启动后会连接注册中心，自注册服务信息
+
+Service Discovery
+服务发现组件，负责服务发现并周期性轮询注册中心中的服务到本地缓存。
+
+Protocol server and client
+支持开发者自己将协议逻辑插入到go chassis中，接入统一的治理和微服务管理当中

docs/intro/features.rst

@@ -0,0 +1,16 @@
+Features
+================================
+- 注册发现：帮助微服务自注册并发现其他微服务
+- 插件化注册中心：默认对接Service Center和文件系统，开发者可自己扩展Kubernetes，Consul，Eureka等服务
+- 限流：提供客户端与服务端限流
+- 负载均衡：提供Filter与Strategy2种方式对实例进行选择，并可定制
+- 熔断：可通过超时时间，错误率，并发量等条件进行熔断控制，保护系统，防止雪崩效应
+- 降级：熔断后可配置降级策略
+- 处理链：支持在一次请求调用中，插入自己的处理逻辑
+- 插件化协议：默认支持http,Highway RPC 2种协议
+- 插件化Cipher：在证书，aksk等敏感数据加载时，支持使用自己的加解密算法
+- Metrics：支持导出Prometheus格式监控数据
+- Tracing：分布式调用链追踪，支持对接Zipkin
+- 日志：支持扩展自己的Writer实现，可上报给kafka，Elasticseach等组件，默认支持本地文件和stdout
+- 动态配置框架：对接不同Source，当Source中的配置项出现变化，将触发事件，让微服务感知，用户可自定义事件触发的动作
+- 配置热加载：负载均衡，熔断，降级等等配置支持运行时热加载

docs/intro/how-it-works.rst

@@ -0,0 +1,15 @@
+How it works
+=========================================
+.. image:: how.png
+
+这里解释运行时发生了什么
+
+不同协议请求进入到各协议Server，Server将具体的协议请求转换为Invocation统一抽象模型，并传入Handler chain，在这里Chassis已经默认实现了很多的Handler，比如熔断，限流等，最终再进入Transport handler，使用具体的协议客户端传输到目标。
+
+每次请求生成的监控数据通过http API导出的方式，由Prometheus收集处理
+
+日志可通过扩展，输出到kafka等服务中也可使用华为公有云APM服务收集
+
+注册中心默认对接Service center
+
+Archaius为动态配置框架，可从各种不同的source中读取配置