==CMP框架(http://cmpTech.info 设计哲学及代码约定

 2016-04-12  //持续更新中

 

注:本WORD文档 已经搬迁至 https://cmptech.gitbooks.io/cmp-api-doc/content/

 

==CMP框架(http://cmpTech.info 设计哲学及代码约定... 1

=核心哲学... 1

=接口规范... 1

=访问权限管理... 1

=接口层类命名规范建议... 2

=URL重写技巧... 2

=关于RESTFUL. 2

=类命名规则... 2

=其它命名约定... 3

=《函数及变量命名法》... 3

=短函数... 4

=部署最佳实践(单机)... 4

=部署最佳实践(其它)... 5

 

=核心哲学

大道至简 —— 我们其实只做了接口的约定定义,其它保持高度灵活。与其说我们是框架,不如说我们只是做了些定义。

=接口规范

核心思想:Class.Method(Param)”

原始调用方式:HTTP 单一入口index.php?class={$className}&method={$methodName}

往上述地址做 HTTP POST json_encode( $param );

 

变体与延伸:

1、【短参数名模式】参数名 class/method/param可以简化为 _c/_m/_p

例:index.php?_c={$className}&_m={$methodName}

2、【多种呼叫方式支持】_p默认为 json化后用POST方法传入。同时框架兼容(但不鼓励)GET显式或 FORM POST方式传入

3、【URL重写支持】通过 url重写实现优雅方式 ./{$className}.{$methodName}.api

例如 ApiTest.PingPong.api

=访问权限管理

为了安全,需要限制访问入口。

框架的方法是在呼叫 $_c.$_p之前用AppAuth.checkApiAccess来限制:


**
上述例子是默认对 _c 进行简单检查。用户可以在这里覆盖AppAuth类来达到对Api对外访问权限的检查,比如说呼叫自己实现的 ApiCheckService类对 $_c/$_m/$_p做基础检查

 

=接口层类命名规范建议

l         ApiXXX 类,较常用,返回一般是 json化的object string 比如 {STS:”OK”}

l         Web类一般接口为 html/plain text的内容返回

l         Wap针对手机浏览器优化带宽的 html/text 返回

l         ussd针对ussd协议的返回【未实战】

l         sms 针对 短信接口的返回【未实战】

l         3g 针对 网络较好的手机浏览器的html/text返回【基本抛弃】

l         Mobile【备用,基本不用】

 

=URL重写技巧

为了使得访问接口变得优雅,在不同的运行环境通过修改 yamlhtaccess 等实现URL重写,把

index.php?class=$className&method=$methodName

URL重写成

l         ,$className,$methodName.web (通常为 WebXXX

l         ,$className,$methodName.json (通常为 WebXXXApiXXX类、JsonXXX类)

l         $className,$methodName.api 2015年起用的统一模式)

 

其它基于经验提出的约定(注但不是必须的,而且在一直进化中。可灵活使用):

** 伪静态 XXX.shtml有特别处理,将跳过php逻辑处理,直接进入模板 shtml.XXX.html

** {$className}.{$methodName}.static 来实现一定程度的伪静态优化

=关于RESTFUL

CMP的约定可以简单地用URL重写实现RESTRESTFUL形式接口

** 但我们认为 RESTFUL 对资源加载效率、HTM模板可视化编辑时并不有利,所以一般不使用

=类命名规则

l         上述ApiOOOO接口层为第一层对外接口层

l         LgcXXXX  Lgc for Logic,即 业务逻辑层

l         AppYYYY   应用层级的数据及对象类 (在命名上,一些衍生项目可以用 {$AppShortCode} 来代替 App这个前缀,比如 SmsdogYYYY )

l         OrmZZZZ   Object-Related-Model,主要是数据库基本封装,尽量不做过多的逻辑。目前主要采用 RedBeanPHP 来实现。

 

简单而直观的理解为

Api=>(参数简单过滤、权限简单校验)=> Lgc逻辑层 (业务逻辑及深度校验)=>业务及模型对象(AppYYYYModelYYYY=> 数据对象(OrmZZZZ)。

 

** 由于历史原因,部分 App/Orm可能不是分得那么清晰,有时跨层直接调用(非常不建议)

** 对比 MVC标准,可以简单地类比 Api层是 Controller(控制器)把请求初加工后转发去的第一层、类比App层和Orm层为Model层,Lgc层理解为业务逻辑层,严格来说也是Model中的一层。

cmp类是一个实现这个 c.m(p) 范式的一个演示型(但生产可用)控制器。

 

特别地强调!我们并不是一个 MVC 框架,我们只是做了一个CMP约定,然后给出实现它的一个范例

 

=其它命名约定

除历史错误俗称的原因以外,类名尽量用大驼峰法,比如

WebBusiness

ApiBusinessReport

ApiBusinessTools

 

方法,如果是Api接口层的public函数,一般用大驼峰,例:

public function WebTest->TestAbc()

 

如果是Api接口类(如Lgc层、App层的public函数),一般用小驼峰,例:

public function pubDef();

 

如果是类保护方法或变量, 单下划线 + 小驼峰,例:

protected function _protDef(){}

protected $_abcVar;

 

如果是私有方法双下划线 + 小驼峰,例:

Private function __privDef();

 

l       由于历史原因,有少量已经用得比较多错误明名函数有可能一时未能全部改回来

l       由于部分旧代码可以接受非驼峰命名(如下划线小写法);

l       部分涉及全大定的专用名词缩写在很难阅读的情况下也会使用下划线法 ACE_ACCT(当然 AceAcct也是可以)

 

 

=《函数及变量命名法》

1. 匈牙利法:

开头字母用变量类型的缩写,其余部分用大驼峰。

比如 iXXX, iptYYY, strZZZ

 

2. 小驼峰式:(little-camel-case)

第一个单词首字母小写,后面其他单词首字母大写。

For example: string firstName = string.Empty;

 

3. 大驼峰式:(big-camel-case) * 有时又叫Pascal法,其实两者基本差不多

每个单词的第一个字母都大写;

For examplestring FirstName = string.Empty;

 

4. C语言法

全小写混合,下划线随意

 

5. 下划线法(phpperl函数常用)

单词之间用下划线间隔,单词本身大小写看情况,但通常是全小写

 

=短函数

短函数 本质上用 函数化 污染 类化而获得便利,所以强迫症患者建议不要用。我们基本也不再增加新的短函数

 

以下是最基本的短函数列表:

 

=inc.local.func.quicklog.php / inc.v5.func.quicklog.sae.php

quicklog_must() 

logger ($filename, txt);

quicklog()   based on the config to do the switch

 

= inc.v5.func.config.php

getConf();

setConf();

 

= inc.v5.lang.ph

getLang();

 

= inc.v5.quick.php

arr2var

var2arr()

arr2var_all()

arr2arr()

 

= inc.v5.sqlsafe.php

qstr();

qstr2();

qstr_arr();

 

=部署最佳实践(单机)

windows

经过最佳实践,可以考虑用国产 kangle。因为

一、    它有使用到 windows特有的 异步IO——“完成端口 IOCP”。所以性能、稳定性都不错。

二、    而且它控制 php-cgifastcgi)模式相当稳定(windows下没有FPM)

三、    能充分把一些跑windows2003的旧服务器给充分利用起来

四、    由于有绿色版本而且有32位版本,比较合适快速部署、速度开发、绿色打包到小型工具型应用系统等。

五、    适合用于生产环境,实测稳定性比apache/isapi模式要稳定非常多(后者差不多偶尔就会卡住,可能是内存泄漏导致,也有可能是一些windows天生的缺陷)

 

Windows下部署时对应的缺陷:

Awindows始终在性能方面略损于linux。经过严格测试,同样硬件配置,linuxwindows快大概2-3倍。

Bwindows下没办法成功编译和使用 php-swoole异步插件

 

Linux

一、WEB可以考虑用 nginx+php-fpm 或者  kangle + php-cgi 结构来组合。

二、当部分核心api高频时,可以在前端的 nginxkangle配置 反向代理 去另外一个专用的 高频应用服务

三、高频应用服务 推荐使用 php-swoole 插件,一般在8核心I7机器上可以轻松压测到 10万级别的RPS

四、可以考虑搭配docker。不过暂时不建议现在(2015年)用于生产环境,可能要等到2017年左右有成熟的UI工具时比较可以考虑。

五、CentOS Ubuntu都是CMP推荐的 Linux版本。

 

Mac OS

Mac下面现在有 brew(类似 yumapt-get)比较方便地安装配置到较新php+swoolenginx等。所以理论上应该是跟 linux等级的性能。所以如果假设考虑自建服务器的话,可以考虑用 macmini +docker来部署小型群集(n>=2)来达到较高的 能效比(*未严谨测试)

 

硬件方面

假设 后端已经安装配置好N>1个应用服务器和数据库,在前端如果条件允许最好可以使用硬件级别的SLB负载均衡。

如果预算不足,用 nginx配置一个负载均衡也可以了,不过这里网卡配置也需要尽量提高。

 

=部署最佳实践(其它)

容器docker部署:

https://github.com/cmptech/cmp_nginxphpfpm_production

** 目标发布可跑 cmp应用的 docker映像,届时在docker环境下我们实现一键启动cmp实例

 

分布式设计:

【待更新完善】CMPTECH正在研究采用哪种方向来实现分布式跨区集群交易数据库及数据交换方法。目前正在观察中的方案包括 codis(分布式redis k-v数据库)、Redis3.0集群、比特币式的去中心化加密交易通道、国产分布式SQL数据库TiDB

 

BPME流程引擎:

【待更新完善】我们正在研发 BPME for PHPBPME for NODEJS 的可视化引擎