diff --git a/README.md b/README.md index 271b115d..083066b9 100644 --- a/README.md +++ b/README.md @@ -246,8 +246,18 @@ docker compose up --build > 注意:默认提供的 docker-compose.yaml 初衷是搭建本机开发调试环境,如果需要产品部署供外网访问,请自行调优配置参数或使用其他方式部署。 -### API 文档 -* `config.yaml` 添加 `Docs:OpenAPI` 功能项: +### 开发文档 +#### Docs文档说明 +`docs`目录提供了各种开发文档,包括: +* [deploy](docs/deploy/) - paopao-ce部署文档 +* [discuss](docs/discuss/) - 开发相关的问题交流论述文档 +* [openapi](docs/openapi/) - paopao-ce后端导出API文档 +* [proposal](docs/proposal/) - paopao-ce功能特性提按文档 +> 比如,关于paopao-ce的设计定位,可以参考[docs/proposal/001-关于paopao-ce的设计定位](docs/proposal/001-关于paopao-ce的设计定位.md),简要阐述了paopao-ce是如何定位自身的。 + +#### API文档 +开发者可以在本地开启`Docs`服务,浏览后端导出的API服务接口文档。 +* `config.yaml` 添加 `Docs` 功能项: ```yaml ... Features: @@ -260,7 +270,7 @@ Features: ```sh make run TAGS='docs' -# visit http://127.0.0.1:8008/docs/openapi +# visit http://127.0.0.1:8011/docs/openapi ``` ### 配置说明 diff --git a/docs/proposal/001-关于paopao-ce的设计定位.md b/docs/proposal/001-关于paopao-ce的设计定位.md index 8d11911f..9176f8b5 100644 --- a/docs/proposal/001-关于paopao-ce的设计定位.md +++ b/docs/proposal/001-关于paopao-ce的设计定位.md @@ -1,6 +1,6 @@ | 编号 | 作者 | 发表时间 | 变更时间 | 版本 | 状态 | | ----- | ----- | ----- | ----- | ----- | ----- | -| 001| 北野 | 2022-11-04 | 2022-12-19 | v1.0 | 提议 | +| 001| 北野 | 2022-11-04 | 2023-01-13 | v1.1 | 提议 | ## 概述 paopao-ce是一个清新文艺的微社区,提供类似Twiter/微博的推文分享服务。paopao-ce的运营形态有点类似WordPress,只不过WordPress是使用PHP语言开发的博客平台,提供的是博客服务,而paopao-ce提供的是类似Twitter的推文分享服务。paopao-ce 让 **个人或小组织** 可以快速、方便的部署一个提供**推文分享服务**的小站点,在有限范围内形成一个友善的社交小圈子微社区。 @@ -37,6 +37,10 @@ paopao-ce目前支持Redis作为缓存存储引擎提供缓存服务,请参考 paopao-ce在代码实现上采用 **单体架构模式、分层设计、功能模块化**,架构设计上可能略显保守,但是在使用新技术上却非常积极,比如搜索引擎就采用了近来新星[Zinc](https://github.com/zinclabs/zinc) /[Meilisearch](https://github.com/meilisearch/meilisearch),同时也不排斥各种云端服务,包括阿里云、腾讯云、华为云的对象存储服务、关系数据库服务等。paopao-ce始终秉持着 **包容并蓄、能用就上、去繁就简** 的架构思维,努力打造一个能 **稳定运行、代码清晰、功能可扩展** 的开源项目。 ![](.assets/006-01.png) +## 从技术探索角度思考 +IT世界是非常精彩的,新技术层出不穷,在各自领域大展身手、大放异彩。作为开发者的我们首要目标当然是以产品为核心,不断的优化服务体验,也不吝啬于新技术的采用以达到更好的产品服务质量。新技术或者某种技术本身,是需要一个环境来支撑其运行、演进,脱离实际环境的技术演进,犹如纸上谈兵,实际效果是存疑的。开发者在研究一项(新)技术时,首先当然是知其然,了解其功能特性、适用场景;再而知其所以然,深入了解其设计原理、知悉其存在的局限等;进而知其不以为然,通过实践,找到技术的最适合场景、知悉其不适合的场景,或与其他技术配合使用,扬长避短,发挥各自的最佳效力以解决具体的事务。这些都是技术探索的通用流程,可以看出,一项技术的探索从陌生到一知半解再到了如指掌,需要一个漫长的过程以及一个技术探索的环境。有些技术的探索,确实需要一个具体的环境,才能更好的研究与实践,比如OBS、Search、Recommended discovery亦或各种云服务的使用、k8s的服务部署等,都需要一个具体的环境来进行技术探索。可以说以需求驱动的技术探索,也更能推进技术本身的不断演进。 +说这么多,这就引出了本节所要说的一个观点了,paopao-ce不仅仅是作为一个提供推文分享服务的产品,也能作为一些(新)技术的探索环境。比如OBS(对象存储服务)、推文搜索服务、推文/用户推荐发现服务、广场推文消息流服务等,都可以作为相应技术领域的技术探索环境,从实践中去检验技术的有效性,更好的推进技术的学习、实践、演进。作为开发者/学习者,也能在理论学习与实际环境中实践(新)技术找到一个平衡,更好、更快的掌握一项(新)技术,这也是paopao-ce的另一价值所在。**路漫漫其修远兮,吾将上下而求索**,用我们开发者的话来说,带着 **上下文(环境/需求)** 去探索(新)技术,或能事半功倍、得心应手。 + ## 从人文角度思考 现在的互联网世界已经非常精彩,各种社交媒体平台琳琅满目,使用体验也非常友好。每个社交平台都有自己的运营方式,都有自己的核心用户群体,也有自己的产品灵魂,都在不断的进行生态演进。比如Twitter、微博都已经从最初的推文分享服务演进到一个成熟的传媒平台,注册用户非常庞大,日均访问PV也是一个惊人的数字,这就注定了平台的运营思维是多维度考量均衡的结果,只能做到让用户群体的大多数人用户体验友好,并不能满足所有人的需求。大平台有大平台的运营模式,小站点有小站点的维系空间。对于类似Twitter这样的推文分享服务,paopao-ce提供一种小站点部署模式,采用类似WordPress的运维模式,让 **个人/小组织** 能快速、便捷的拥有一个提供推文分享服务的小站点,以填补那些在大平台下难以享受到的用户体验,享受小圈子内的自由空间。 @@ -71,3 +75,6 @@ paopao-ce在代码实现上采用 **单体架构模式、分层设计、功能 #### v1.0(2022-12-19) - 北野 * 补充部分内容 + +#### v1.1(2023-01-13) - 北野 +* 补充 从技术探索角度思考 描述