README.md · Guzi/uim-open-src

uim开源版说明
===============

uim是作者历经长时间思考和实践所沉淀的一套API架构，包含了前端的调用封装、网络层封装、以及可扩展的接口消费端。为了避免闭门造车，特发布此开源版本，邀请各位朋友和同行了解，希望能得到大家的认可和建议，互相学习！

uim在作者不断的验证、重构、优化和实践下，已经应用在了许多的web系统中。其中有一些独特的架构思想和奇妙设计，当然也沉淀了不少成熟的功能和稳定的模块。但当决定发布开源版之时，却发现仍有一些难以决断的设计，难在想快速发布核心版本的同时又不愿意过于简陋，想包含更多的特性又不愿意让大家难于部署和理解，另外还要思考公共版本与私有版本在一些技术方案上的不同实现。无论以后还会遇到多少问题需要思考，我们希望有你一起参与！

目前主要包含的特性有：

+ 原生支持分布式部署
 + 框架升级机制
 + 多项目支持
 + 统一的接口网关
 + 可不同语言合作接口开发
 + 会话支持
 + 日志精确到用户
 + 接口层单机成本最小化、消费能力最大化
 + 灵活限流，自动扩容，避免超出服务能力的洪峰请求
 + 前端js封装，简单接口调用，无需关注网络传输协议
 + 接口模拟支持
 + 枚举的配置和使用
 + 参数的配置和使用

> uim开源版所需的运行环境：nginx，php（或其他web语言环境），nodejs，redis。

<p align=center>
  <img src="./uim框架服务节点介绍与接口执行流程简单示意图.png" alt="uim">
</p>
<p align=center>
  uim框架服务节点介绍与接口执行流程简单示意图
</p>

---
详细开发文档参考 [uim开源版完全开发手册](http://open-src.uim.cn/doc) 和 [在线示例](https://demo.open-src.uim.site)

uim开发者社区正在建设中，请先加入QQ群：801261291

## 源代码目录结构

~~~
uim-open-src-v1.0  代码库目录
├─api                        接口消费端工程目录
│  ├─framework               接口框架目录
│  │  ├─phpm-1.0             基于原生php7.*的极简api框架（开发中）
│  │  └─thinkphp-5.0.24      基于thinkphp5.0.24的api框架（建议首选）
│  │
│  └─consumer.js             接口消费进程
│
├─command                    命令文件目录
│  ├─docker-run-*.sh         创建容器并在容器中安装相应软件环境
│  └─server-init.sh          初始服务器环境
│
├─data                       数据目录
│  ├─install.sql             数据库初始文件
│  └─update-*.sql            数据库更新文件
│
├─html                       静态资源目录
│  ├─js                      核心js
│  │  ├─socket.io.js         socket.io前端核心文件
│  │  └─uim.js               uim前端核心文件
│  ├─demo-*.html             调用示例
│  └─index.html              首页/说明文件
│
├─socket                     套接字服务工程目录
│  ├─router                  路由程序目录
│  │  ├─config.js            配置文件
│  │  ├─socket-router.js     路由主程序
│  │  └─uim.js               uim公共函数
│  └─server                  服务程序目录
│     ├─config.js            配置文件
│     ├─socket-server.js     服务主程序
│     └─uim.js               uim公共函数
│
├─LICENSE.txt                授权说明文件
├─README.md                  README 文件
~~~

## 各工程说明

### 接口消费端

* 接口消费端可部署多台，根据接口并发情况及成本要求，灵活增加或减少服务器数量。
* 接口执行过程中，由consumer.js将用户请求从队列中取出，交由后端接口程序执行后返回。
* 为便于入手和快速开发应用，接口后端框架优先提供了php版，基于国内较为流行的thinkphp5.0.24进行了简单封装。
* consumer.js中已默认将接口路径配置为127.0.0.1/api/router。
* 后续会逐步封装基于其他语言/框架编的接口后端框架（因接口层的业务特性，基本以解释型语言为主）。您也可以使用任意web后端语言自行封装。

### html静态资源

> 根据前端架构方案采用适合的引入方式：

* 单页应用中，在body结束时引入uim.js并调用uim.init()；
* 传统网站中，首先创建公共的初始文件（或直接修改uim.init.js），在各html页面body结束时先后引入uim.js与uim.init.js；
* 管理后台类型建议采用单页方案（正在分别基于layuiadmin和bootstrap进行封装，计划开源，敬请期待）。

### socket路由与服务

* 在uim架构中，所有涉及的服务都能够实现横向扩展。为便于初步了解，可暂时将/socket/router/socket-router.js理解为只部署在一台服务器上，而/socket/server/socket-server.js可根据需要部署在N台服务器上。
* socket-router不做转发，仅返回当前最空闲的socket-server的服务器地址给浏览器；
* 客户端请求接口时，由浏览器环境下的uim.js封装请求并发送至socket-server，等待socket-server异步或同步返回。

## 部署说明

为便于交流理解，所有服务器环境以使用docker官方centos镜像为基础，全部使用手工命令搭建。弄懂后即可自行搭建本地开发环境。
#### 准备三个（或以上）域名和对应的https证书
> 例如：
* socket路由：socket-router.xxx.com
* socket长连接服务：socket-server1.xxx.com、socket-server2.xxx.com、socket-servern.xxx.com
* 静态页面资源：www.xxx.com

> uim开源版在线demo域名配置参考：
* 静态资源：demo.open-src.uim.site
* socket路由：demo.open-src.uim.site（域名与静态资源相同）
* socket长连接服务：s1.demo.open-src.uim.site、s2.demo.open-src.uim.site、s3.demo.open-src.uim.site

#### 准备服务器环境和代码

* 首先您需要在互联网上有至少一台服务器，如果您已经是uim开发社区的会员，可以向群主申请一台测试服务器用于体验部署。
* 如果您只准备了一台服务器且只有一个公网IP，您可以将以上所有域名都解析到这一个IP上。如果您有更多的服务器和公网IP，则可根据情况分别部署。
* 操作系统：centos7.*以上。
* 阅读/command/server-init.sh，并根据需要执行相关命令。

#### 创建容器

* redis实例1个，用于存放接口请求队列
* nginx实例1个，用于提供静态资源访问，对应域名www.xxx.com。
* nodejs实例1个，用于运行socket-router，对应域名socket-router.xxx.com。
* nodejs实例n个，用于运行socket-server，对应域名socket-server(1-n).xxx.com。
* php实例n个，用于运行接口消费端（需要同时支持nodejs）。

> 初次使用docker可参考/command/docker-run-*.sh，您也可以自行选择其他容器技术或不使用容器部署。

> 测试部署时可以无须分别创建以上容器，全部使用一个域名并且将所有实例安装在一个容器中（或直接使用您以往的环境）会节省很多操作，但如果需要测试架构在高并发情景下的负载效率，或是在实际生产环境中，建议严格分离为多台服务器而不要混合安装在一台服务器内。

还没有使用过centos或docker？请自行学习或到群里找学习链接。

## 升级与维护说明

#### 统一开发规范

强烈建议大家按照统一规范进行开发，不要随意修改UIM核心程序和数据结构！

这不仅有助于技术交流，更重要的是当UIM的核心库、内置程序、数据库表等发生版本升级时，由于您对UIM核心程序或相关数据结构的修改，可能会增加系统的升级风险，导致您的系统不能升级，甚至造成系统崩溃。

如果您确实需要修改UIM核心程序和数据库结构，请在此之前先到群里交流，是否有其他方案。属于通用需求的，可以投票建议官方优先或尽快实现该通用需求。

#### 升级注意事项

当UIM开源版发布更新后，将通过会员群消息、短信、电子邮件或其他方式进行通知。您应当充分根据更新版本的描述信息和代码库中的源程序变动细节，自行评估和承担升级风险。

不要在您的生产环境中直接使用svn进行更新，而应当仔细检查新版本中相对于您的生产环境中的变动，手动导出增量包进行上传。

上传到生产环境前还应当先建立测试环境进行相应的测试验证，确保结果正常，并做好生产环境的备份，必要时还需要将您的系统先暂停服务，待升级操作完全实施并确认无误后再开放服务。

## 方向与规划

虽然目前仅把uim作为一个API架构来介绍，但我们对它的未来有很多的设计，期待这些都能够一步一步的实现。务实的说，至少可以把uim作为应用的快速开发框架，另外我们会计划长期维护，并为开源版加入适当多的通用功能，做出更好的规避问题的设计，尽可能让使用uim的开发者减少重复造轮子，高质高效的工作，把更多的时间用于投资自己和陪伴家人！

uim开源版目前主要以最简化的框架核心功能为基础，同时尽可能为适应持续开发/持续集成做相应的设计。部署层面以原生支持分布式为特点，。其中的各种环境依赖可能会让开发新手觉得框架部署涉及命令繁多，希望一切部署妥当后，你会觉得不虚此行。

## 使用uim开发应用

### 开发规范

#### 除了为实现业务需要在接口层进行开发外，尽可能不要修改其他文件

如果您考虑后续升级的便利，请不要自行修改uim自带数据库，及以下文件或目录：（以下路径相对源代码库目录而言，您可能将其拷贝和部署在其他目录中）

> 接口消费工程
* /api/consumer.js
* /api/framework/thinkphp-5.0.24/

> html静态资源
* /html/js/socket.io.js
* /html/js/uim.js

> 套接字服务工程
* /socket/router/config.js
* /socket/router/socket-router.js
* /socket/router/uim.js
* /socket/server/config.js
* /socket/server/socket-server.js
* /socket/server/uim.js

#### 接口消费工程开发规范

* 请根据您选用的接口框架阅读相应开发文档(http://open-src.uim.site/doc/api-framework)

### 
如果您已经了解uim开源版的设计思想和技术原理，熟练相关技术，并认可uim的稳定性、可靠性，计划使用uim开源版作为您的下一个应用开发框架，我们很愿意为您提供必要的支持。

如果您和您的团队在使用uim进行开发或维护时发生系统故障，经确认属于uim本身的设计缺陷的，我们将尽快修复，并可视情况对您的系统故障进行协助，但不会为您使用开源版时发生的系统故障进行赔偿，因为开源版属于落地部署，自行维护，使用方应该对开发、部署与维护的各环节进行评估并负所有责任。

诚然，我们以及整个uim社区都会极力避免在正式发布的版本中出现缺陷，我们的初衷是希望给您带来效率的提升、成本的下降、更高的安全性和易维护性！

为使您真正感受到使用uim所带来的优势，在您基于uim开源版进行开发、部署、维护时，请尽可能遵照uim社区的建议，避免对uim相关核心文件和数据库进行修改，这可以让您的系统更容易同步到uim的更新版本，否则可能导致我们无法对您的系统进行技术支持。

具体的开发规范以社区发布的文章、文档为准，请注意悉知。
我们衷心祝愿您的系统稳定运行，事业越做越强！

## 版权信息

参阅 [LICENSE.txt](LICENSE.txt)

Guzi/uim-open-src

简介

发行版

贡献者

近期动态

Guzi/uim-open-src .gitee-modal { width: 500px !important; }

简介

发行版

贡献者

近期动态

搜索帮助

Guzi/uim-open-src