From c273df485d476b33ab65be9daf2745c0b8e81fb3 Mon Sep 17 00:00:00 2001 From: Wen Ming Date: Wed, 27 May 2020 20:23:26 +0800 Subject: [PATCH] doc: removed external links and docs. (#1619) --- CODE_STYLE.md | 393 -------------------------------------------------- README.md | 9 +- README_CN.md | 11 +- 3 files changed, 5 insertions(+), 408 deletions(-) delete mode 100644 CODE_STYLE.md diff --git a/CODE_STYLE.md b/CODE_STYLE.md deleted file mode 100644 index 8b7a4ca2ef65..000000000000 --- a/CODE_STYLE.md +++ /dev/null @@ -1,393 +0,0 @@ - - -# OpenResty Lua Coding Style Guide - -## indentation -Use 4 spaces as an indent in OpenResty, although Lua does not have such a grammar requirement. - -``` ---No -if a then -ngx.say("hello") -end -``` - -``` ---yes -if a then - ngx.say("hello") -end -``` - -You can simplify the operation by changing the tab to 4 spaces in the editor you are using. - -## Space -On both sides of the operator, you need to use a space to separate: - -``` ---No -local i=1 -local s = "apisix" -``` - -``` ---Yes -local i = 1 -local s = "apisix" -``` - -## Blank line -Many developers will bring the development habits of other languages to OpenResty, such as adding a semicolon at the end of the line. - -``` ---No -if a then -    ngx.say("hello"); -end; -``` - -Adding a semicolon will make the Lua code look ugly and unnecessary. Also, don't want to save the number of lines in the code, the latter turns the multi-line code into one line in order to appear "simple". This will not know when the positioning error is in the end of the code: - -``` ---No -if a then ngx.say("hello") end -``` - -``` ---yes -if a then - ngx.say("hello") -end -``` - -The functions needs to be separated by two blank lines: -``` ---No -local function foo() -end -local function bar() -end -``` - -``` ---Yes -local function foo() -end - - -local function bar() -end -``` - -If there are multiple if elseif branches, they need a blank line to separate them: -``` ---No -if a == 1 then - foo() -elseif a== 2 then - bar() -elseif a == 3 then - run() -else - error() -end -``` - -``` ---Yes -if a == 1 then - foo() - -elseif a== 2 then - bar() - -elseif a == 3 then - run() - -else - error() -end -``` - -## Maximum length per line -Each line cannot exceed 80 characters. If it exceeds, you need to wrap and align: - -``` ---No -return limit_conn_new("plugin-limit-conn", conf.conn, conf.burst, conf.default_conn_delay) -``` - -``` ---Yes -return limit_conn_new("plugin-limit-conn", conf.conn, conf.burst, - conf.default_conn_delay) -``` - -When the linefeed is aligned, the correspondence between the upper and lower lines should be reflected. For the example above, the parameters of the second line of functions are to the right of the left parenthesis of the first line. - -If it is a string stitching alignment, you need to put `..` in the next line: -``` ---No -return limit_conn_new("plugin-limit-conn" .. "plugin-limit-conn" .. - "plugin-limit-conn") -``` - -``` ---Yes -return limit_conn_new("plugin-limit-conn" .. "plugin-limit-conn" - .. "plugin-limit-conn") -``` - -``` ---Yes -return "param1", "plugin-limit-conn" - .. "plugin-limit-conn") -``` - -## Variable -Local variables should always be used, not global variables: -``` ---No -i = 1 -s = "apisix" -``` - -``` ---Yes -local i = 1 -local s = "apisix" -``` - -Variable naming uses the `snake_case` style: -``` ---No -local IndexArr = 1 -local str_Name = "apisix" -``` - -``` ---Yes -local index_arr = 1 -local str_name = "apisix" -``` - -Use all capitalization for constants: -``` ---No -local max_int = 65535 -local server_name = "apisix" -``` - -``` ---Yes -local MAX_INT = 65535 -local SERVER_NAME = "apisix" -``` - -## Table -Use `table.new` to pre-allocate the table: -``` ---No -local t = {} -for i = 1, 100 do - t[i] = i -end -``` - -``` ---Yes -local new_tab = require "table.new" -local t = new_tab(100, 0) -for i = 1, 100 do - t[i] = i -end -``` - -Don't use `nil` in an array: -``` ---No -local t = {1, 2, nil, 3} -``` - -If you must use null values, use `ngx.null` to indicate: -``` ---Yes -local t = {1, 2, ngx.null, 3} -``` - -## String -Do not splicing strings on the hot code path: -``` ---No -local s = "" -for i = 1, 100000 do - s = s .. "a" -end -``` - -``` ---Yes -local t = {} -for i = 1, 100000 do - t[i] = "a" -end -local s = table.concat(t, "") -``` - -## Function -The naming of functions also follows `snake_case`: -``` ---No -local function testNginx() -end -``` - -``` ---Yes -local function test_nginx() -end -``` - -The function should return as early as possible: -``` ---No -local function check(age, name) - local ret = true - if age < 20 then - ret = false - end - - if name == "a" then - ret = false - end - -- do something else - return ret -end -``` - -``` ---Yes -local function check(age, name) - if age < 20 then - return false - end - - if name == "a" then - return false - end - -- do something else - return true -end -``` - -## Module -All require libraries must be localized: -``` ---No -local function foo() - local ok, err = ngx.timer.at(delay, handler) -end -``` - -``` ---Yes -local timer_at = ngx.timer.at - -local function foo() - local ok, err = timer_at(delay, handler) -end -``` - -For style unification, `require` and `ngx` also need to be localized: -``` ---No -local core = require("apisix.core") -local timer_at = ngx.timer.at - -local function foo() - local ok, err = timer_at(delay, handler) -end -``` - -``` ---Yes -local ngx = ngx -local require = require -local core = require("apisix.core") -local timer_at = ngx.timer.at - -local function foo() - local ok, err = timer_at(delay, handler) -end -``` - -## Error handling -For functions that return with error information, the error information must be judged and processed: -``` ---No -local sock = ngx.socket.tcp() -local ok = sock:connect("www.google.com", 80) -ngx.say("successfully connected to google!") -``` - -``` ---Yes -local sock = ngx.socket.tcp() -local ok, err = sock:connect("www.google.com", 80) -if not ok then - ngx.say("failed to connect to google: ", err) - return -end -ngx.say("successfully connected to google!") -``` - -The function you wrote yourself, the error message is to be returned as a second parameter in the form of a string: -``` ---No -local function foo() - local ok, err = func() - if not ok then - return false - end - return true -end -``` - -``` ---No -local function foo() - local ok, err = func() - if not ok then - return false, {msg = err} - end - return true -end -``` - -``` ---Yes -local function foo() - local ok, err = func() - if not ok then - return false, "failed to call func(): " .. err - end - return true -end -``` diff --git a/README.md b/README.md index f6b4a4f34a7e..a32c79baf8ec 100644 --- a/README.md +++ b/README.md @@ -39,8 +39,6 @@ APISIX is a cloud-based microservices API gateway that handles traditional north APISIX provides dynamic load balancing, authentication, rate limiting, other plugins through plugin mechanisms, and supports plugins you develop yourself. -For more detailed information, see the [White Paper](https://static.apiseven.com/2020/05/1589275276-Choosing-the-Right-Microservice-API-Gateway-for-the-Enterprise-User.pdf). - ![](doc/images/apisix.png) ## Features @@ -50,7 +48,7 @@ A/B testing, canary release, blue-green deployment, limit rate, defense against - **All platforms** - Cloud-Native: Platform agnostic, No vendor lock-in, APISIX can run from bare-metal to Kubernetes. - Run Environment: Both OpenResty and Tengine are supported. - - Supports [ARM64](https://zhuanlan.zhihu.com/p/84467919): Don't worry about the lock-in of the infra technology. + - Supports ARM64: Don't worry about the lock-in of the infra technology. - **Multi protocols** - [TCP/UDP Proxy](doc/stream-proxy.md): Dynamic TCP/UDP proxy. @@ -106,7 +104,6 @@ A/B testing, canary release, blue-green deployment, limit rate, defense against - High performance: The single-core QPS reaches 18k with an average delay of less than 0.2 milliseconds. - [Fault Injection](doc/plugins/fault-injection.md) - [REST Admin API](doc/admin-api.md): Using the REST Admin API to control Apache APISIX, which only allows 127.0.0.1 access by default, you can modify the `allow_admin` field in `conf/config.yaml` to specify a list of IPs that are allowed to call the Admin API. Also note that the Admin API uses key auth to verify the identity of the caller. **The `admin_key` field in `conf/config.yaml` needs to be modified before deployment to ensure security**. - - [Python SDK](https://github.com/api7/apache-apisix-python-sdk) - External Loggers: Export access logs to external log management tools. ([HTTP Logger](doc/plugins/http-logger.md), [TCP Logger](doc/plugins/tcp-logger.md), [Kafka Logger](doc/plugins/kafka-logger.md), [UDP Logger](doc/plugins/udp-logger.md)) - **Highly scalable** @@ -121,7 +118,7 @@ APISIX Installed and tested in the following systems(OpenResty MUST >= 1.15.8.1, CentOS 7, Ubuntu 16.04, Ubuntu 18.04, Debian 9, Debian 10, macOS, **ARM64** Ubuntu 18.04 Steps to install APISIX: -1. Installation runtime dependencies: OpenResty and etcd, refer to [documentation](doc/install-dependencies.md) +1. Installation runtime dependencies: Nginx and etcd, refer to [documentation](doc/install-dependencies.md) 2. There are several ways to install Apache APISIX: - [Source Release](doc/how-to-build.md#installation-via-source-release) - [RPM package](doc/how-to-build.md#installation-via-rpm-package-centos-7) for CentOS 7 @@ -171,8 +168,6 @@ Do not need to fill the user name and password, log in directly. The dashboard only allows 127.0.0.1 by default, and you can modify `allow_admin` in `conf/config.yaml` by yourself, to list the list of IPs allowed to access. -We provide an online dashboard [demo version](http://apisix.iresty.com), make it easier for you to understand APISIX. - ## Benchmark Using AWS's 8 core server, APISIX's QPS reach to 140,000 with a latency of only 0.2 ms. diff --git a/README_CN.md b/README_CN.md index b9143268b24a..2ce2cadba327 100644 --- a/README_CN.md +++ b/README_CN.md @@ -29,7 +29,7 @@ APISIX 是一个云原生、高性能、可扩展的微服务 API 网关。 -它是基于 OpenResty 和 etcd 来实现，和传统 API 网关相比，APISIX 具备动态路由和插件热加载，特别适合微服务体系下的 API 管理。 +它是基于 Nginx 和 etcd 来实现，和传统 API 网关相比，APISIX 具备动态路由和插件热加载，特别适合微服务体系下的 API 管理。 ## 为什么选择 APISIX？ @@ -39,8 +39,6 @@ APISIX 是基于云原生的微服务 API 网关，它是所有业务流量的 APISIX 通过插件机制，提供动态负载平衡、身份验证、限流限速等功能，并且支持你自己开发的插件。 -更多详细的信息，可以查阅[ APISIX 的白皮书](https://static.apiseven.com/2020/05/1589275281-%E4%BC%81%E4%B8%9A%E7%94%A8%E6%88%B7%E5%A6%82%E4%BD%95%E9%80%89%E6%8B%A9%E5%BE%AE%E6%9C%8D%E5%8A%A1-API-%E7%BD%91%E5%85%B3.pdf) - ![](doc/images/apisix.png) ## 功能 @@ -50,7 +48,7 @@ A/B 测试、金丝雀发布(灰度发布)、蓝绿部署、限流限速、抵 - **全平台** - 云原生: 平台无关，没有供应商锁定，无论裸机还是 Kubernetes，APISIX 都可以运行。 - 运行环境: OpenResty 和 Tengine 都支持。 - - 支持 [ARM64](https://zhuanlan.zhihu.com/p/84467919): 不用担心底层技术的锁定。 + - 支持 ARM64: 不用担心底层技术的锁定。 - **多协议** - [TCP/UDP 代理](doc/stream-proxy-cn.md): 动态 TCP/UDP 代理。 @@ -106,7 +104,6 @@ A/B 测试、金丝雀发布(灰度发布)、蓝绿部署、限流限速、抵 - 高性能：在单核上 QPS 可以达到 18k，同时延迟只有 0.2 毫秒。 - [故障注入](doc/plugins/fault-injection-cn.md) - [REST Admin API](doc/admin-api-cn.md): 使用 REST Admin API 来控制 Apache APISIX，默认只允许 127.0.0.1 访问，你可以修改 `conf/config.yaml` 中的 `allow_admin` 字段，指定允许调用 Admin API 的 IP 列表。同时需要注意的是，Admin API 使用 key auth 来校验调用者身份，**在部署前需要修改 `conf/config.yaml` 中的 `admin_key` 字段，来保证安全。** - - [Python SDK](https://github.com/api7/apache-apisix-python-sdk) - 外部日志记录器：将访问日志导出到外部日志管理工具。([HTTP Logger](doc/plugins/http-logger.md), [TCP Logger](doc/plugins/tcp-logger.md), [Kafka Logger](doc/plugins/kafka-logger.md), [UDP Logger](doc/plugins/udp-logger.md)) - **高度可扩展** @@ -118,7 +115,7 @@ A/B 测试、金丝雀发布(灰度发布)、蓝绿部署、限流限速、抵 APISIX 在以下操作系统中可顺利安装并做过运行测试，需要注意的是：OpenResty 的版本必须 >= 1.15.8.1： -CentOS 7, Ubuntu 16.04, Ubuntu 18.04, Debian 9, Debian 10, macOS, **[ARM64](https://zhuanlan.zhihu.com/p/84467919)** Ubuntu 18.04 +CentOS 7, Ubuntu 16.04, Ubuntu 18.04, Debian 9, Debian 10, macOS, **ARM64** Ubuntu 18.04 安装 APISIX 的步骤： 1. 安装运行时依赖：OpenResty 和 etcd，参考[依赖安装文档](doc/install-dependencies-cn.md) @@ -172,8 +169,6 @@ cp -r dist/* . Dashboard 默认只允许 127.0.0.1 访问。你可以自行修改 `conf/config.yaml` 中的 `allow_admin` 字段，指定允许访问 dashboard 的 IP 列表。 -我们部署了一个在线的 [Dashboard](http://apisix.iresty.com) ，方便你了解 APISIX。 - ## 性能测试 使用 AWS 的 8 核心服务器来压测 APISIX，QPS 可以达到 140000，同时延时只有 0.2 毫秒。