[GitHub] [apisix] spacewander commented on a change in pull request #3650: docs: plugin-develop.md adds ctx and conf descriptions

[GitBox <gi...@apache.org>]

spacewander commented on a change in pull request #3650:
URL: https://github.com/apache/apisix/pull/3650#discussion_r581561149



##########
File path: doc/plugin-develop.md
##########
@@ -295,7 +295,188 @@ end
 
 ## implement the logic
 
-Write the logic of the plugin in the corresponding phase.
+Write the logic of the plugin in the corresponding phase. There are two parameters `conf` and `ctx` in the `phase` method, take the `limit-conn` plugin configuration as an example.
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+    "methods": ["GET"],
+    "uri": "/index.html",
+    "id": 1,
+    "plugins": {
+        "limit-conn": {
+            "conn": 1,
+            "burst": 0,
+            "default_conn_delay": 0.1,
+            "rejected_code": 503,
+            "key": "remote_addr"
+        }
+    },
+    "upstream": {
+        "type": "roundrobin",
+        "nodes": {
+            "39.97.63.215:80": 1
+        }
+    }
+}'
+```
+
+### conf parameter
+
+The `conf` parameter caches the relevant configuration information of the plugin. The `conf` data obtained by `core.log.warn(core.json.encode(conf))` is as follows.
+
+```lua
+function _M.access(conf, ctx)
+    core.log.warn("conf: ", core.json.encode(conf))
+    ......
+end
+```
+
+conf:
+
+```json
+{
+    "rejected_code":503,
+    "burst":0,
+    "default_conn_delay":0.1,
+    "conn":1,
+    "key":"remote_addr"
+}
+```
+
+### ctx parameter
+
+The `ctx` parameter caches the data information related to the request. The `ctx` data obtained by `core.log.warn(core.json.encode(ctx, true))` is as follows.
+
+```lua
+function _M.access(conf, ctx)
+    core.log.warn("ctx: ", core.json.encode(ctx, true))
+    ......
+end
+```
+
+ctx:
+
+```json
+{
+    "matched_upstream":{

Review comment:
       This value will change across versions. And it also depends on where you log it. We just need to tell users how to check it.

##########
File path: doc/plugin-develop.md
##########
@@ -295,7 +295,188 @@ end
 
 ## implement the logic
 
-Write the logic of the plugin in the corresponding phase.
+Write the logic of the plugin in the corresponding phase. There are two parameters `conf` and `ctx` in the `phase` method, take the `limit-conn` plugin configuration as an example.
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+    "methods": ["GET"],
+    "uri": "/index.html",
+    "id": 1,
+    "plugins": {
+        "limit-conn": {
+            "conn": 1,
+            "burst": 0,
+            "default_conn_delay": 0.1,
+            "rejected_code": 503,
+            "key": "remote_addr"
+        }
+    },
+    "upstream": {
+        "type": "roundrobin",
+        "nodes": {
+            "39.97.63.215:80": 1
+        }
+    }
+}'
+```
+
+### conf parameter
+
+The `conf` parameter caches the relevant configuration information of the plugin. The `conf` data obtained by `core.log.warn(core.json.encode(conf))` is as follows.

Review comment:
       The word here is confusing. The `conf` parameter is the relevant configuration information of the plugin. It doesn't serve as cache.

##########
File path: doc/plugin-develop.md
##########
@@ -295,7 +295,188 @@ end
 
 ## implement the logic
 
-Write the logic of the plugin in the corresponding phase.
+Write the logic of the plugin in the corresponding phase. There are two parameters `conf` and `ctx` in the `phase` method, take the `limit-conn` plugin configuration as an example.

Review comment:
       Better to use "phase method" instead of "`phase` method" as there is not a method called `phase`.




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org