membphis commented on a change in pull request #814: doc: add plugin develop document. URL: https://github.com/apache/incubator-apisix/pull/814#discussion_r346128491
########## File path: doc/plugins/plugin-develop-cn.md ########## @@ -0,0 +1,180 @@ +<!-- +# +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +--> +[English](plugin-develop.md) + +# 目录 +- [**检查外部依赖**](#检查外部依赖) +- [**插件命名与配置**](#插件命名与配置) +- [**配置描述与校验**](#配置描述与校验) +- [**确定执行阶段**](#确定执行阶段) +- [**编写执行逻辑**](#编写执行逻辑) +- [**编写测试用例**](#编写测试用例) + + +## 检查外部依赖 + +如果你的插件，涉及到一些外部的依赖和三方库，请首先检查一下依赖项的内容。如果插件需要用到共享内存，需要在 __bin/apisix__ 文 +件里面进行申明，例如： + +```nginx + lua_shared_dict plugin-limit-req 10m; + lua_shared_dict plugin-limit-count 10m; + lua_shared_dict prometheus-metrics 10m; + lua_shared_dict plugin-limit-conn 10m; + lua_shared_dict upstream-healthcheck 10m; + lua_shared_dict worker-events 10m; + + # for openid-connect plugin + lua_shared_dict discovery 1m; # cache for discovery metadata documents + lua_shared_dict jwks 1m; # cache for JWKs + lua_shared_dict introspection 10m; # cache for JWT verification results +``` + +如果插件本身的依赖，需要在 Nginx 初始化启动，则可能需要在 __lua/apisix.lua__ 文件的初始化方法 http_init 中添加逻辑，并且 +可能需要在 __bin/apisix__ 文件中，对 Nginx 配置文件生成的部分，添加一些你需要的处理。 + +注：插件本身提供了 init 方法。方便插件加载后做初始化动作。 + +## 插件命名与配置 + +给插件取一个很棒的名字，确定插件的加载优先级，然后在 __conf/config.yaml__ 文件中添加上你的插件名。例如 key-auth 这个插件， +需要在代码里指定插件名称（名称是插件的唯一标识，不可重名），在 __lua/apisix/plugins/key-auth.lua__ 文件中可以看到 + +```lua + local plugin_name = "key-auth" + ... + local _M = { + version = 0.1, + priority = 2500, + type = 'auth', + name = plugin_name, + schema = schema, + } +``` + +在 __conf/config.yaml__ 配置文件中，列出了启用的插件（都是以插件名指定的） + +```yaml +plugins: # plugin list + - example-plugin + - limit-req + - limit-count + - limit-conn + - key-auth + - prometheus + - node-status + - jwt-auth + - zipkin + - ip-restriction + - grpc-transcode + - serverless-pre-function + - serverless-post-function + - openid-connect + - proxy-rewrite + - redirect +``` + +注：先后顺序与执行顺序无关 + +## 配置描述与校验 + +定义插件的配置项，以及对应的 [Json Schema](#https://json-schema.org) 描述，并完成对 json 的校验，这样方便对配置的数据规 +格进行验证，以确保数据的完整性以及程序的健壮性。同样，我们以 key-auth 插件为例，看看他的配置数据： + +```json + "key-auth": { + "key": "auth-one" + } +``` + +插件的配置数据比较简单，只支持一个命名为 key 的属性，那么我们看下他的 Schema 描述： + +```lua + local schema = { + type = "object", + properties = { + key = {type = "string"}, + } + } +``` + +同时，需要实现 __check_schema(conf)__ 方法，完成规格的校验。 Review comment: `完成规格的校验` -> `完成配置参数的合法性校验` ---------------------------------------------------------------- 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: us...@infra.apache.org With regards, Apache Git Services
