From 7f999b8a153034d6cb316a2c140c1031a3cdd81f Mon Sep 17 00:00:00 2001 From: zds <49744633+zds-s@users.noreply.github.com> Date: Fri, 18 Oct 2024 14:35:36 +0800 Subject: [PATCH] =?UTF-8?q?feature=20=E8=A1=A5=E5=85=85=20Http=20=E8=A7=84?= =?UTF-8?q?=E8=8C=83=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .vitepress/theme/index.ts | 1 - .vitepress/theme/styles/block.css | 374 ------------------------------ docs/zh/backend/base/router.md | 204 ++++++++++++++++ 3 files changed, 204 insertions(+), 375 deletions(-) delete mode 100644 .vitepress/theme/styles/block.css diff --git a/.vitepress/theme/index.ts b/.vitepress/theme/index.ts index a841981..efc69c8 100644 --- a/.vitepress/theme/index.ts +++ b/.vitepress/theme/index.ts @@ -38,7 +38,6 @@ import '@imengyu/vue3-context-menu/lib/vue3-context-menu.css' import './styles/var.css' -import './styles/block.css' import './styles/blur.css' import './styles/vp-code-group.css' import './styles/vp-code.css' diff --git a/.vitepress/theme/styles/block.css b/.vitepress/theme/styles/block.css deleted file mode 100644 index 572d121..0000000 --- a/.vitepress/theme/styles/block.css +++ /dev/null @@ -1,374 +0,0 @@ -/* .vitepress/theme/style/custom-block.css */ -/* 深浅色卡 */ -:root { - --custom-block-info-left: #cccccc; - --custom-block-info-bg: #fafafa; - - --custom-block-tip-left: #009400; - --custom-block-tip-bg: #e6f6e6; - - --custom-block-warning-left: #e6a700; - --custom-block-warning-bg: #fff8e6; - - --custom-block-danger-left: #e13238; - --custom-block-danger-bg: #ffebec; - - --custom-block-note-left: #4cb3d4; - --custom-block-note-bg: #eef9fd; - - --custom-block-important-left: #a371f7; - --custom-block-important-bg: #f4eefe; - - --custom-block-caution-left: #e0575b; - --custom-block-caution-bg: #fde4e8; -} - -.dark { - --custom-block-info-left: #cccccc; - --custom-block-info-bg: #474748; - - --custom-block-tip-left: #009400; - --custom-block-tip-bg: #003100; - - --custom-block-warning-left: #e6a700; - --custom-block-warning-bg: #4d3800; - - --custom-block-danger-left: #e13238; - --custom-block-danger-bg: #4b1113; - - --custom-block-note-left: #4cb3d4; - --custom-block-note-bg: #193c47; - - --custom-block-important-left: #a371f7; - --custom-block-important-bg: #230555; - - --custom-block-caution-left: #e0575b; - --custom-block-caution-bg: #391c22; -} - - -/* 标题字体大小 */ -.custom-block-title { - font-size: 16px; -} - -/* info容器:背景色、流体边框 */ -.custom-block.info { - border-left: none; - background-color: var(--custom-block-info-bg); - position: relative; - transition: all .3s; -} - -/* info容器:svg图 */ -.custom-block.info [class*="custom-block-title"]::before { - content: ''; - background-image: url("data:image/svg+xml;utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M12 22C6.477 22 2 17.523 2 12S6.477 2 12 2s10 4.477 10 10-4.477 10-10 10zm-1-11v6h2v-6h-2zm0-4v2h2V7h-2z' fill='%23ccc'/%3E%3C/svg%3E"); - width: 20px; - height: 20px; - display: inline-block; - vertical-align: middle; - position: relative; - margin-right: 4px; - left: -5px; - top: -1px; -} - -/* info容器:流体边框 */ -.custom-block.info::before, -.custom-block.info::after { - content: ""; - position: absolute; - top: -2px; - left: -2px; - right: -2px; - bottom: -2px; - border: 2px solid var(--custom-block-info-left); - transition: all .5s; - animation: clippath 6s infinite linear; - border-radius: 10px; -} - -/* info容器:流体边框动画 */ -.custom-block.info::after { - animation: clippath 6s infinite -3s linear; -} - - - - -/* TIP容器::背景色、流体边框 */ -.custom-block.tip { - border-left: none; - background-color: var(--custom-block-tip-bg); - position: relative; - transition: all .3s; -} - -/* TIP容器:svg图 */ -.custom-block.tip [class*="custom-block-title"]::before { - content: ''; - background-image: url("data:image/svg+xml;utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath fill='%23009400' d='M7.941 18c-.297-1.273-1.637-2.314-2.187-3a8 8 0 1 1 12.49.002c-.55.685-1.888 1.726-2.185 2.998H7.94zM16 20v1a2 2 0 0 1-2 2h-4a2 2 0 0 1-2-2v-1h8zm-3-9.995V6l-4.5 6.005H11v4l4.5-6H13z'/%3E%3C/svg%3E"); - width: 20px; - height: 20px; - display: inline-block; - vertical-align: middle; - position: relative; - margin-right: 4px; - left: -5px; - top: -2px; -} - -/* TIP容器:流体边框 */ -.custom-block.tip::before, -.custom-block.tip::after { - content: ""; - position: absolute; - top: -2px; - left: -2px; - right: -2px; - bottom: -2px; - border: 2px solid var(--custom-block-tip-left); - transition: all .5s; - animation: clippath 6s infinite linear; - border-radius: 10px; -} - -/* TIP容器:流体边框动画 */ -.custom-block.tip::after { - animation: clippath 6s infinite -3s linear; -} - - - - -/* WARNING:背景色、流体边框 */ -.custom-block.warning { - border-left: none; - background-color: var(--custom-block-warning-bg); - position: relative; - transition: all .3s; -} - -/* WARNING:svg图 */ -.custom-block.warning [class*="custom-block-title"]::before { - content: ''; - background-image: url("data:image/svg+xml;utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 1024 1024'%3E%3Cpath d='M576.286 752.57v-95.425q0-7.031-4.771-11.802t-11.3-4.772h-96.43q-6.528 0-11.3 4.772t-4.77 11.802v95.424q0 7.031 4.77 11.803t11.3 4.77h96.43q6.528 0 11.3-4.77t4.77-11.803zm-1.005-187.836 9.04-230.524q0-6.027-5.022-9.543-6.529-5.524-12.053-5.524H456.754q-5.524 0-12.053 5.524-5.022 3.516-5.022 10.547l8.538 229.52q0 5.023 5.022 8.287t12.053 3.265h92.913q7.032 0 11.803-3.265t5.273-8.287zM568.25 95.65l385.714 707.142q17.578 31.641-1.004 63.282-8.538 14.564-23.354 23.102t-31.892 8.538H126.286q-17.076 0-31.892-8.538T71.04 866.074q-18.582-31.641-1.004-63.282L455.75 95.65q8.538-15.57 23.605-24.61T512 62t32.645 9.04 23.605 24.61z' fill='%23e6a700'/%3E%3C/svg%3E"); - width: 20px; - height: 20px; - display: inline-block; - vertical-align: middle; - position: relative; - margin-right: 4px; - left: -5px; -} - -/* WARNING容器:流体边框 */ -.custom-block.warning::before, -.custom-block.warning::after { - content: ""; - position: absolute; - top: -2px; - left: -2px; - right: -2px; - bottom: -2px; - border: 2px solid var(--custom-block-warning-left); - transition: all .5s; - animation: clippath 6s infinite linear; - border-radius: 10px; -} - -/* WARNING容器:流体边框动画 */ -.custom-block.warning::after { - animation: clippath 6s infinite -3s linear; -} - - - - -/* DANGER容器:背景色、流体边框 */ -.custom-block.danger { - border-left: none; - background-color: var(--custom-block-danger-bg); - position: relative; - transition: all .3s; -} - -/* DANGER容器:svg图 */ -.custom-block.danger [class*="custom-block-title"]::before { - content: ''; - background-image: url("data:image/svg+xml;utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M12 2c5.523 0 10 4.477 10 10v3.764a2 2 0 0 1-1.106 1.789L18 19v1a3 3 0 0 1-2.824 2.995L14.95 23a2.5 2.5 0 0 0 .044-.33L15 22.5V22a2 2 0 0 0-1.85-1.995L13 20h-2a2 2 0 0 0-1.995 1.85L9 22v.5c0 .171.017.339.05.5H9a3 3 0 0 1-3-3v-1l-2.894-1.447A2 2 0 0 1 2 15.763V12C2 6.477 6.477 2 12 2zm-4 9a2 2 0 1 0 0 4 2 2 0 0 0 0-4zm8 0a2 2 0 1 0 0 4 2 2 0 0 0 0-4z' fill='%23e13238'/%3E%3C/svg%3E"); - width: 20px; - height: 20px; - display: inline-block; - vertical-align: middle; - position: relative; - margin-right: 4px; - left: -5px; - top: -1px; -} - - -/* DANGER容器:流体边框 */ -.custom-block.danger::before, -.custom-block.danger::after { - content: ""; - position: absolute; - top: -2px; - left: -2px; - right: -2px; - bottom: -2px; - border: 2px solid var(--custom-block-danger-left); - transition: all .5s; - animation: clippath 6s infinite linear; - border-radius: 10px; -} - -/* DANGER容器:流体边框动画 */ -.custom-block.danger::after { - animation: clippath 6s infinite -3s linear; -} - - - - - - - - -/* GitHub风格警告 */ - - - -/* NOTE容器:背景色、流体边框 */ -.custom-block.note { - border-left: none; - background-color: var(--custom-block-note-bg); - position: relative; - transition: all .3s; -} - -/* NOTE容器:svg图 */ -.custom-block.note [class*="custom-block-title"]::before { - content: ''; - background-image: url("data:image/svg+xml;utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M12 22C6.477 22 2 17.523 2 12S6.477 2 12 2s10 4.477 10 10-4.477 10-10 10zm-1-11v6h2v-6h-2zm0-4v2h2V7h-2z' fill='%234cb3d4'/%3E%3C/svg%3E"); - width: 20px; - height: 20px; - display: inline-block; - vertical-align: middle; - position: relative; - margin-right: 4px; - left: -5px; - top: -1px; -} - -/* NOTE容器:流体边框 */ -.custom-block.note.github-alert::before, -.custom-block.note.github-alert::after { - content: ""; - position: absolute; - top: -2px; - left: -2px; - right: -2px; - bottom: -2px; - border: 2px solid var(--custom-block-note-left); - transition: all .5s; - animation: clippath 6s infinite linear; - border-radius: 10px; -} - -/* NOTE容器:流体边框动画 */ -.custom-block.note.github-alert::after { - animation: clippath 6s infinite -3s linear; -} - - - - -/* IMPORTANT容器:背景色、流体边框 */ -.custom-block.important { - border-left: none; - background-color: var(--custom-block-important-bg); - position: relative; - transition: all .3s; -} - -/* IMPORTANT容器:svg图 */ -.custom-block.important [class*="custom-block-title"]::before { - content: ''; - background-image: url("data:image/svg+xml;utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 1024 1024'%3E%3Cpath d='M512 981.333a84.992 84.992 0 0 1-84.907-84.906h169.814A84.992 84.992 0 0 1 512 981.333zm384-128H128v-42.666l85.333-85.334v-256A298.325 298.325 0 0 1 448 177.92V128a64 64 0 0 1 128 0v49.92a298.325 298.325 0 0 1 234.667 291.413v256L896 810.667v42.666zm-426.667-256v85.334h85.334v-85.334h-85.334zm0-256V512h85.334V341.333h-85.334z' fill='%23a371f7'/%3E%3C/svg%3E"); - width: 20px; - height: 20px; - display: inline-block; - vertical-align: middle; - position: relative; - margin-right: 4px; - left: -5px; - top: -1px; -} - - -/* IMPORTANT容器:流体边框 */ -.custom-block.important.github-alert::before, -.custom-block.important.github-alert::after { - content: ""; - position: absolute; - top: -2px; - left: -2px; - right: -2px; - bottom: -2px; - border: 2px solid var(--custom-block-important-left); - transition: all .5s; - animation: clippath 6s infinite linear; - border-radius: 10px; -} - -/* IMPORTANT容器:流体边框动画 */ -.custom-block.important.github-alert::after { - animation: clippath 6s infinite -3s linear; -} - - - - -/* CAUTION容器:背景色、流体边框 */ -.custom-block.caution { - border-left: none; - background-color: var(--custom-block-caution-bg); - position: relative; - transition: all .3s; -} - -/* CAUTION容器:svg图 */ -.custom-block.caution [class*="custom-block-title"]::before { - content: ''; - background-image: url("data:image/svg+xml;utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M12 2c5.523 0 10 4.477 10 10v3.764a2 2 0 0 1-1.106 1.789L18 19v1a3 3 0 0 1-2.824 2.995L14.95 23a2.5 2.5 0 0 0 .044-.33L15 22.5V22a2 2 0 0 0-1.85-1.995L13 20h-2a2 2 0 0 0-1.995 1.85L9 22v.5c0 .171.017.339.05.5H9a3 3 0 0 1-3-3v-1l-2.894-1.447A2 2 0 0 1 2 15.763V12C2 6.477 6.477 2 12 2zm-4 9a2 2 0 1 0 0 4 2 2 0 0 0 0-4zm8 0a2 2 0 1 0 0 4 2 2 0 0 0 0-4z' fill='%23e13238'/%3E%3C/svg%3E"); - width: 20px; - height: 20px; - display: inline-block; - vertical-align: middle; - position: relative; - margin-right: 4px; - left: -5px; - top: -1px; -} - -/* CAUTION容器:流体边框 */ -.custom-block.caution.github-alert::before, -.custom-block.caution.github-alert::after { - content: ""; - position: absolute; - top: -2px; - left: -2px; - right: -2px; - bottom: -2px; - border: 2px solid var(--custom-block-caution-left); - transition: all .5s; - animation: clippath 6s infinite linear; - border-radius: 10px; -} - -/* CAUTION容器:流体边框动画 */ -.custom-block.caution.github-alert::after { - animation: clippath 6s infinite -3s linear; -} diff --git a/docs/zh/backend/base/router.md b/docs/zh/backend/base/router.md index 593755a..596edb8 100644 --- a/docs/zh/backend/base/router.md +++ b/docs/zh/backend/base/router.md @@ -15,6 +15,210 @@ ::: +## Http 规范 + +### 路由命名 + +在现代化应用程序中，Restful 风格已经风靡人心。在 `2.0` 以及 `3.0` 版本中。我们推荐按照以下说明规范你的 API 接口 + +- 获取数据使用 GET +- 修改数据使用 PUT +- 删除数据使用 DELETE +- 新增数据使用 POST + +以自带的 `UserController` 举例。 + +- GET `/admin/user/list` 获取用户列表 +- PUT `/admin/user/{id}` 修改单一用户 +- POST `/admin/user` 创建用户 +- DELETE `/admin/user` 删除用户 + +你应该保证你的应用程序尽量贴合官方推荐规范,但请不要`无脑参考`. +虽然技术的规范会使你的应用程序更加壮硕。但是不能一味追求规范。需要以业务的可持续迭代为主 + +### HTTP 响应结构体 + +在 `3.0` 版本中。我们推荐并遵循的是全局的响应对象为 `\App\Http\Common\Result`，也就是意味着 +在你的接口开发中，为了方便后续的`迭代升级`以及遵循统一的规范。你应该返回 `\App\Http\Common\Result` 实例。而不是自己拼接响应参数 +同时我们也提供了 `App\Http\Common\Controller\AbstractController` 方便在日常开发中能够快速返回 `Result` 实例 + +只需在你的控制器中使用 `return $this->success()` 即可组装成一个全新的 `Result` 实例 + +::: code-group + +```php [Result] +message === null) { + $this->message = ResultCode::getMessage($this->code->value); + } + } + + public function toArray(): array + { + return [ + 'code' => $this->code->value, + 'message' => $this->message, + 'data' => $this->data, + ]; + } +} + +``` + +```php [Common\Controller\AbstractController] +abstract class AbstractController +{ + protected function success(mixed $data = [], ?string $message = null): Result + { + return new Result(ResultCode::SUCCESS, $message, $data); + } + + protected function error(?string $message = null, mixed $data = []): Result + { + return new Result(ResultCode::FAIL, $message, $data); + } + + protected function json(ResultCode $code, mixed $data = [], ?string $message = null): Result + { + return new Result($code, $message, $data); + } +} +``` + +```php [Admin\Controller\AbstractController] +getRequest()->input('page', 1); + } + + protected function getPageSize(): int + { + return (int) $this->getRequest()->input('page_size', 10); + } + + protected function getRequest(): RequestInterface + { + return ApplicationContext::getContainer()->get(RequestInterface::class); + } +} + +``` + +::: + +### Http Result Code + +默认提供了一个 `App\Http\Common\ResultCode` 枚举。并准备了一些公用的 code 方便业务开发. + +```php [Result] +