Merge pull request apache#55 from cityiron/docs

docs Former-commit-id: 104c23d [formerly 6dffacd] Former-commit-id: e780789
tydhot · Nov 16, 2020 · 8b84f29 · 8b84f29
2 parents 20876dc + 64ce2b7
commit 8b84f29
Show file tree

Hide file tree

Showing 29 changed files with 375 additions and 123 deletions.
diff --git a/docs/common/README.md b/docs/common/README.md
@@ -0,0 +1,5 @@
+# Common
+
+* [FAQ](faq.md)
+* [Roadmap](roadmap.md)
+* [Proxy arguments](proxy-arguments.md)
diff --git a/docs/common/faq.md b/docs/common/faq.md
@@ -0,0 +1,13 @@
+# FAQ
+
+In case you did not find any answer here and in [closed issues](https://github.com/dubbogo/dubbo-go-proxy/issues?q=is%3Aissue+is%3Aclosed), [create new issue](https://github.com/dubbogo/dubbo-go-proxy/issues/new/choose).
+
+### Why first dubbogo request timeout?
+
+First request for dubbogo need create a GenericService, will exec ReferenceConfig.GenericLoad(), it takes some account of time. If you worry about this case, you need preheating apis for yourself.
+
+We plan an auto preheating in the future.
+
+
+
+
diff --git a/docs/common/proxy-arguments.md b/docs/common/proxy-arguments.md
@@ -0,0 +1,11 @@
+# dubbo-go-proxy arguments
+
+Proxy accepts multiple arguments that can be used to customize it a bit.
+
+## Arguments
+
+| Argument name | Default value | Description |
+|---------------|---------------|-------------|
+| -c or config  |        -      | proxy project config, core for listener config, like port, cluster..|
+|-a or api-config|      -       | api config, for api-gateway way's custom api                        |
+
diff --git a/docs/common/roadmap.md b/docs/common/roadmap.md
@@ -0,0 +1,17 @@
+# Roadmap
+
+The following table contains a priority-ordered list of work items and features the team plans to work on.
+
+|Area|Item|Relative priority|Status|
+|----|----|-----------------|------|
+| api | basic api definition | P0 |      |
+| api | dubbo metadata | P0 |      |
+| api |  http metadata | P0 |      |
+| auto | zookeeper registry | P1 |      |
+| auto | consul registry | P1 |      |
+| auto | kubernetes registry | P1 |      |
+| filter | basic filter definition  | P0 |      |
+| plugin | go plugin | P1 |      |
+| client | basic client definition | P0 |      |
+| client | dubbo client | P0 |      |
+| client | http client | P0 |      |
diff --git a/docs/concept.md b/docs/concept.md
diff --git a/docs/developer/README.md b/docs/developer/README.md
@@ -0,0 +1,6 @@
+# Developer Guide
+
+* [Concept](concept.md)
+* [Auto Registry](auto-registy.md)
+* [Filter](filter.md)
+* [Log](log.md)
diff --git a/docs/developer/auto-registy.md b/docs/developer/auto-registy.md
@@ -0,0 +1,7 @@
+# Auto Registry
+
+A feature easy for users to use dubbo-go-proxy.
+
+## dubbo
+
+Find dubbo rpc interface from dubbo's register, use rules to significantly reduces the amount of manual registration. This feature is doing.
diff --git a/docs/developer/concept.md b/docs/developer/concept.md
@@ -0,0 +1,5 @@
+# Concept
+
+## Term
+
+the term in dubbo-go-proxy 
diff --git a/docs/developer/filter.md b/docs/developer/filter.md
@@ -0,0 +1,6 @@
+# Filter
+
+Filter is the composition of filter chain, make use more control.
+
+## Default filter
+
diff --git a/docs/developer/log.md b/docs/developer/log.md
@@ -0,0 +1,19 @@
+# Log
+
+How to view logs in dubbo-go-proxy.
+
+## DEBUG log
+
+** dubbo 请求日志**
+
+```bash
+2020-11-14T20:59:58.841+0800    DEBUG   dubbo/dubbo.go:149      [dubbo-go-proxy] invoke, method:GetUserByName, types:[java.lang.String], reqData:[tc]
+```
+
+** dubbo 响应日志**
+
+```bash
+2020-11-14T20:59:58.843+0800    DEBUG   remote/call.go:96       [dubbo-go-proxy] resp : {map[age:18 i_d:0001 name:tc]}
+```
+
+
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,24 @@
+# dubbo-go-proxy Documentation
+
+## [Common](common/README.md)
+
+* [FAQ](common/faq.md)
+* [Roadmap](common/roadmap.md)
+* [Proxy arguments](common/proxy-arguments.md)
+
+## [Samples](sample/README.md)
+
+* [dubbo](sample/dubbo.md)
+* [http](sample/http.md)
+
+## [User Guide](user/README.md)
+
+* [Api Model](user/api.md)
+* [Installation](user/installation.md)
+
+## [Developer Guide](developer/README.md)
+
+* [Concept](developer/concept.md)
+* [Auto Registry](developer/auto-registy.md)
+* [Filter](developer/filter.md)
+* [Log](developer/log.md)
diff --git a/docs/quick_start.md b/docs/quick_start.md
diff --git a/docs/sample/README.md b/docs/sample/README.md
@@ -0,0 +1,4 @@
+# Samples
+
+* [dubbo](sample/dubbo.md)
+* [http](sample/http.md)
diff --git a/docs/sample/dubbo-error.md b/docs/sample/dubbo-error.md
@@ -0,0 +1,17 @@
+# dubbo error
+
+err log in proxy
+
+```bash
+2020-11-14T17:56:58.652+0800    ERROR   remote/call.go:89       [dubboproxy go] client do err:data is exist!
+github.com/dubbogo/dubbo-go-proxy/pkg/logger.Errorf
+        /Users/tc/Documents/workspace_2020/dubbo-go-proxy/pkg/logger/logging.go:52
+github.com/dubbogo/dubbo-go-proxy/pkg/filter/remote.(*clientFilter).doRemoteCall
+        /Users/tc/Documents/workspace_2020/dubbo-go-proxy/pkg/filter/remote/call.go:89
+github.com/dubbogo/dubbo-go-proxy/pkg/filter/remote.(*clientFilter).Do.func1
+        /Users/tc/Documents/workspace_2020/dubbo-go-proxy/pkg/filter/remote/call.go:66
+github.com/dubbogo/dubbo-go-proxy/pkg/context/http.(*HttpContext).Next
+        /Users/tc/Documents/workspace_2020/dubbo-go-proxy/pkg/context/http/context.go:54
+github.com/dubbogo/dubbo-go-proxy/pkg/filter/timeout.(*timeoutFilter).Do.func1.1
+        /Users/tc/Documents/workspace_2020/dubbo-go-proxy/pkg/filter/timeout/timeout.go:74
+```
diff --git a/docs/sample/dubbo.md b/docs/sample/dubbo.md
@@ -0,0 +1,7 @@
+# dubbo
+
+* [dubbo-query](dubbogo-query.md)
+* [dubbo-body](dubbogo-body.md)
+* [dubbo-error](dubbo-error.md)
+
+
diff --git a/docs/sample/dubbogo-body.md b/docs/sample/dubbogo-body.md
@@ -0,0 +1,51 @@
+# Get the parameter from the body
+
+> POST request
+
+## passthrough
+
+**config**
+
+```yaml
+name: proxy
+description: proxy sample
+resources:
+  - path: '/api/v1/test-dubbo/user'
+    type: restful
+    description: user
+    methods:
+      - httpVerb: POST
+              onAir: true
+              timeout: 10s
+              inboundRequest:
+                requestType: http            
+              integrationRequest:
+                requestType: dubbo
+                mappingParams:
+                  - name: requestBody._all
+                    mapTo: 0
+                applicationName: "UserProvider"
+                interface: "com.ic.user.UserProvider"
+                method: "CreateUser"
+                paramTypes: [ "com.ikurento.user.User" ]
+                group: "test"
+                version: 1.0.0
+                clusterName: "test_dubbo"
+```
+
+**request**
+
+```bash
+curl localhost:8888/api/v1/test-dubbo/user -X POST -d '{"name":"tiecheng","id":"0001","age":18}' --header "Content-Type: application/json"
+```
+
+**response**
+
+```bash
+{"age":18,"i_d":"0001","name":"tiecheng"}
+```
+
+## mapping
+
+
+
diff --git a/docs/sample/dubbogo-query.md b/docs/sample/dubbogo-query.md
@@ -0,0 +1,49 @@
+# Get the parameter from the query
+
+> GET request
+
+## simple
+
+**config**
+
+```yaml
+name: proxy
+description: proxy sample
+resources:
+  - path: '/api/v1/test-dubbo/user'
+    type: restful
+    description: user
+    methods:
+      - httpVerb: GET
+        onAir: true
+        timeout: 100ms
+        inboundRequest:
+          requestType: http
+          queryStrings:
+            - name: name
+              required: true
+        integrationRequest:
+          requestType: dubbo
+          mappingParams:
+            - name: queryStrings.name
+              mapTo: 0
+          applicationName: "UserProvider"
+          interface: "com.ic.user.UserProvider"
+          method: "GetUserByName"
+          paramTypes: [ "java.lang.String" ]
+          group: "test"
+          version: 1.0.0
+          clusterName: "test_dubbo"
+```
+
+**request**
+
+```bash
+curl localhost:8888/api/v1/test-dubbo/user?name=tc -X GET 
+```
+
+**response**
+
+```bash
+{"age":18,"i_d":"0001","name":"tc"}
+```
diff --git a/docs/sample/http.md b/docs/sample/http.md
@@ -0,0 +1 @@
+# http
diff --git a/docs/user/README.md b/docs/user/README.md
@@ -0,0 +1,5 @@
+# User Guide
+
+* [Quick Start](start.md)
+* [Api Model](api.md)
+* [Installation](installation.md)
diff --git a/docs/api_gateway_config_en.md → docs/user/api.md b/docs/api_gateway_config_en.md → docs/user/api.md
@@ -1,6 +1,13 @@
-# API Gateway
-API is the key feature of the dubbo-go-proxy. With this feature, you can expose your dubbo service as a HTTP service.
-## Configuration
+# Api
+
+Introduction to API model, recommended reading before customizing API for api_config.yaml.
+
+## Api Gateway
+
+API is the key feature of the dubbo-go-proxy. With this feature, you can expose your dubbo service as an HTTP service.
+
+### Configuration
+
 Sample:
 ``` yaml
 name: api name

diff --git a/docs/user/installation.md b/docs/user/installation.md
@@ -0,0 +1,2 @@
+# Installation
+