From f4521f7aca5243d68658e7da20b487d15924aa2e Mon Sep 17 00:00:00 2001 From: satori Date: Mon, 29 Nov 2021 01:35:04 +0800 Subject: [PATCH] beta --- README.md | 151 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 109 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index a984088..3fcab4c 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,20 @@ -# shizukana -nodejs restful webapi +# かな +Nodejs 构建的 RESTful 风格 WEB API + + + +1. 抽象化以扩大泛用性, 适用于各种形态的项目 +2. 无须配置依赖项的, 使用内嵌数据库 +3. 单文件, 代码不到 300 行, 易于维护, 易于扩展 + + + +由于使用已被大量实践的协议与风格建议, 文档中不再讲解此类细节, 这里将假设你已经了解: + +1. RESTful 风格 URL +2. HTTP Method 资源操作方式 + + ## Install ```bash @@ -19,56 +34,108 @@ node index pm2 start node --name shizukana -- index ``` + + ## 特征 -1. 抽象化以扩大泛用性 -2. 无须配置依赖项的 -### 程序结构 -1. 抽象细分原则模块化 -2. 免配置原则 -3. 分层原则 -4. 分布式原则 -5. 解耦扩容原则 +`/:name/:_id` + +RESTful 风格 API, URL形式为两段 name是对象类型, _id是对象id + +如发表一篇文章, -#### 接口层 -对外接口允许多服务终端, 服务集群皆为公开阵列 -允许即刻熔断 - -1. 每地区一台或多台伺服器, 伺服器只是节点, 不属于中心 -2. 具体落盘数据格式与冗余如何与接口节点无关 - -则终端连接伺服器通过可用时期节点列表缓存 -终端连接信任域列表, 使用证书校验节点有效性 -终端从信任域获取列表, 并将列表缓存, 特定更新周期或事件对伺服器列表更新 - -/全功能伺服器 -任意节点都是伺服器之一, 没有分级且发挥节点所有效能 -节点给出可用节点列表, - -节点之间如何通信实现可用列表和数据的同步? - -1. 主动从节点阵列获取 -2. 被动从节点阵列收取 - -事件模型中, 当伺服节点产生事件, 向有限域传递事件 -但由于传递过程时间有滞后, 无法保障事件发生顺序准确性 -因而, 有因果勾连的事物须在唯一时空与媒介发生 -不同节点并不能属于同一时空, 且节点本以在不同时空降低滞后性效用而存在, 以及隔离 +## 使用示例 -小团体伺服节点在不同伺服器之间无感转移(媒介) -1. 媒介作为通讯会话, 可轻易建立与销毁 -2. 伺服器作为沟通节点提供连接,如 websocket -3. 在节点与节点之间建立通信, 为媒介 -4. 多个节点可能同时通信 -5. 但效率不如此次会话所有终端连接同一伺服节点 -6. 且算力是定量, 无论节点多少 -### 使用示例 +#### 创建用户 + +当程序在本地运行时, localhost:2333 + +```javascript +fetch() +``` + + + + + + + +#### 对象列表 + +`GET` /:name + +```javascript +{ + page: Number, // 当前页码(默认为1) + pagesize: Number, // 分页大小(默认20) + sort: string, // 排序方式(只能是对象的通用属性名) + desc: Number, // 0或1, 正序和倒序 + uid: string, // 指定发布者uid查询 + like: bool, // 查询自己点赞了的对象 + post: bool, // 查询自己评论过的对象 + count: bool, // 计数器(在返回的headers中附带列表统计信息) +} +``` + +- 除以上通用属性外, 对象的私有属性也可以用于查询 +- 如果查询参数包含了不存在的参数, 将返回 400 错误 +- 查询列表时, 相同的查询条件有15s缓存 +- 如果查询公共的列表, 只返回状态为 pubilc的 +- 如果查询自己的列表, 则同时返回私有状态的 + + + +查询示例: + +```javascript +fetch('/book').then(Response => Response.json()).then(data => { + console.log(data) +}) + +// 返回结果 +[ + {_id:'xxx', data:'xxxx'}, + {_id:'xxx', data:'xxxx'} +] +``` + + + +创建示例: + +```javascript +fetc('/book', { + method: 'POST', + headers: { + 'Accept': 'application/json', + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + name: '创建一本新书', + data: '书的内容' + }), +}).then(Response => Response.json()).then(data => { + console.log(data) +}) + +// 返回结果 +{ + _id: 'xxx', + uid: 'xxx', + name: '创建一本新书', + data: '书的内容' +} +``` + + + +#### 对象实体