腾讯PHP开发规范方案

1、. .27/27海豹平台开发规v1.0腾讯科技（）*版本信息&等级版本更改日期更改要点说明编制审核批准V1.02013/12/24新建wilsonwsongV1.12013/12/26修订rusherding文档等级：部公开目录 TOC o 1-3 h z u HYPERLINK l _RefHeading_Toc654海豹平台开发规v1.01 HYPERLINK l _RefHeading_Toc95541 引言5 HYPERLINK l _RefHeading_Toc87761.1 定义与缩略语5 HYPERLINK l _RefHeading_Toc156331.2 参考文档5 HYPE

2、RLINK l _RefHeading_Toc131581.3 目的5 HYPERLINK l _RefHeading_Toc187641.4 适用围5 HYPERLINK l _RefHeading_Toc302371.5 标准化作用5 HYPERLINK l _RefHeading_Toc226742 目录结构规6 HYPERLINK l _RefHeading_Toc64412.1 框架路径6 HYPERLINK l _RefHeading_Toc305792.2 应用目录结构6 HYPERLINK l _RefHeading_Toc134592.2.1 配置config7 HYPERL

3、INK l _RefHeading_Toc32382.2.2 控制器controllers7 HYPERLINK l _RefHeading_Toc204222.2.3 模型models7 HYPERLINK l _RefHeading_Toc305422.2.4 视图views8 HYPERLINK l _RefHeading_Toc299992.2.5 国际化messages8 HYPERLINK l _RefHeading_Toc21962.2.6 组件components8 HYPERLINK l _RefHeading_Toc102342.2.7 命令commands8 HYPERL

4、INK l _RefHeading_Toc314762.2.8 临时目录runtime8 HYPERLINK l _RefHeading_Toc298742.3 路径别名8 HYPERLINK l _RefHeading_Toc237782.3.1 类型导入8 HYPERLINK l _RefHeading_Toc234923 PHP编码规9 HYPERLINK l _RefHeading_Toc209223.1 标签9 HYPERLINK l _RefHeading_Toc33823.2 编码9 HYPERLINK l _RefHeading_Toc253693.3 注释9 HYPERLIN

5、K l _RefHeading_Toc263943.3.1 文件注释9 HYPERLINK l _RefHeading_Toc117903.3.2 类注释10 HYPERLINK l _RefHeading_Toc298183.3.3 方法注释10 HYPERLINK l _RefHeading_Toc211923.3.4 属性注释11 HYPERLINK l _RefHeading_Toc227463.3.5 其它11 HYPERLINK l _RefHeading_Toc6753.4 命名规则11 HYPERLINK l _RefHeading_Toc134353.4.1 文件11 HYP

6、ERLINK l _RefHeading_Toc101873.4.2 类12 HYPERLINK l _RefHeading_Toc122913.4.3 函数/方法12 HYPERLINK l _RefHeading_Toc150553.4.4 变量名12 HYPERLINK l _RefHeading_Toc46763.4.5 常量名12 HYPERLINK l _RefHeading_Toc158213.5 书写规则13 HYPERLINK l _RefHeading_Toc64373.5.1 文件13 HYPERLINK l _RefHeading_Toc210413.5.2 行13 H

7、YPERLINK l _RefHeading_Toc222783.5.3 缩进13 HYPERLINK l _RefHeading_Toc176763.5.4 控制结构13 HYPERLINK l _RefHeading_Toc82143.5.5 运算符16 HYPERLINK l _RefHeading_Toc39903.5.6 引号16 HYPERLINK l _RefHeading_Toc121393.5.7 关键词17 HYPERLINK l _RefHeading_Toc297883.5.8 函数17 HYPERLINK l _RefHeading_Toc107273.5.9 类17

8、 HYPERLINK l _RefHeading_Toc263973.5.10 属性18 HYPERLINK l _RefHeading_Toc54163.5.11 方法18 HYPERLINK l _RefHeading_Toc72794 数据库命名规20 HYPERLINK l _RefHeading_Toc192224.1 命名规20 HYPERLINK l _RefHeading_Toc183304.2 实体命名20 HYPERLINK l _RefHeading_Toc304184.2.1 前缀命名20 HYPERLINK l _RefHeading_Toc834.2.2 后缀命名2

9、1 HYPERLINK l _RefHeading_Toc199734.3 字段命名21 HYPERLINK l _RefHeading_Toc223294.3.1 后缀命名22 HYPERLINK l _RefHeading_Toc45944.4 字段类型22 HYPERLINK l _RefHeading_Toc59484.4.1 数值类型22 HYPERLINK l _RefHeading_Toc321714.4.2 字符类型23 HYPERLINK l _RefHeading_Toc254444.4.3 时间类型23 HYPERLINK l _RefHeading_Toc131474.

10、4.4 ENUM&SET23 HYPERLINK l _RefHeading_Toc70444.4.5 LOB 类型23 HYPERLINK l _RefHeading_Toc21864.5 表结构设计24 HYPERLINK l _RefHeading_Toc20224.5.1 适度冗余24 HYPERLINK l _RefHeading_Toc209234.5.2 尽量使用NOT NULL24 HYPERLINK l _RefHeading_Toc28004.5.3 索引24 HYPERLINK l _RefHeading_Toc40655 附件24 HYPERLINK l _RefHea

11、ding_Toc208165.1 附录一：MYSQL保留字24引言定义与缩略语缩略词说明海豹平台运维中心提供的研发平台，提供框架、公共基础组件、公共业务组件加速业务的日常研发工作参考文档海豹平台WIKI： HYPERLINK :/wiki.seals.webdev /wiki.seals.webdev./目的本规由编程原则组成，融合并提炼了开发人员长时间积累下来的成熟经验，意在帮助形成良好一致的编程风格。以达到事半功倍的效果，如果有需要本文档会不定期更新。适用围如无特殊说明，以下规则要求完全适用于基于海豹平台框架开发的应用，同时也可大部分适用于部门其他PHP项目。标准化作用当一个软件项目尝试着

12、遵守公共一致的标准时，可以使参与项目的开发人员更容易了解项目中的代码、弄清程序的状况。使新的参与者可以很快的适应环境，防止部分参与者出于节省时间的需要，自创一套风格并养成终生的习惯，导致其它人在阅读时浪费过多的时间和精力。而且在一致的环境下，也可以减少编码出错的机会。缺陷是由于每个人的标准不同，所以需要一段时间来适应和改变自己的编码风格，暂时性的降底了工作效率。从使项目长远健康的发展以与后期更高的团队工作效率来考虑暂时的工作效率降低是值得的，也是必须要经过的一个过程。标准不是项目成功的关键，但可以帮助我们在团队协作中有更高的效率并且更加顺利的完成既定的任务。程序员可以了解任何代码，弄清程序的状

13、况新人可以很快的适应环境 防止新接触PHP的开发出于节省时间的需要，自创一套风格并养成终生的习惯 防止新接触PHP的开发一次次的犯同样的错误 在一致的环境下，可以减少犯错的机会 目录结构规框架路径框架引用路径必须采用绝对路径，托管的开发、测试和正式环境必须为：/data/php/framework应用目录结构应用需要严格参考以下目录安排代码位置：webroot/ index.php Web 应用入口脚本文件 index-test.php 功能测试使用的入口脚本文件 assets/ 包含公开的资源文件 css/ 包含 CSS 文件 images/ 包含图片文件 themes/ 包含应用主题 pr

14、otected/ 包含受保护的应用文件 modc 命令行脚本 modc.bat Windows 下的命令行脚本 modc.php 命令行 PHP 脚本 commands/ 包含自定义的 modc 命令 components/ 包含可重用的用户组件config/ 包含配置文件 controllers/ 包含控制器的类文件 SiteController.php 默认控制器的类文件 extensions/ 包含第三方扩展 messages/ 包含翻译过的消息(i8n相关) models/ 包含模型的类文件 runtime/ 包含临时生成的文件 tests/ 包含测试脚本 views/ 包含控制器的视

15、图和布局文件 layouts/ 包含布局视图文件 main.php 所有视图的默认布局site/ 包含 site 控制器的视图文件 system/ 包含系统视图文件配置config存放应用配置目录，具体参考 HYPERLINK :/wiki.seals.webdev /index.php/入口脚本WII人口 HYPERLINK :/wiki.seals.webdev /index.php/入口脚本K HYPERLINK :/wiki.seals.webdev /index.php/入口脚本脚本控制器controllers存放控制逻辑的类目录，具体参考 HYPERLINK :/wiki.seal

16、s.webdev /index.php/控制器WIKI控制器模型models存放模型定义的类目录，具体参考 HYPERLINK :/wiki.seals.webdev /index.php/模型WIKI模型视图views存放视图文件的目录，具体目录参考 HYPERLINK :/wiki.seals.webdev /index.php/视图WIKI视图国际化messages存放国际化定义文件的目录组件components存放组件的类目录，具体目录参考 HYPERLINK :/wiki.seals.webdev /index.php/组件WIKI组件命令commands存放Console命令的类目

17、录，具体目录参考 HYPERLINK :/wiki.seals.webdev /index.php/Cli使用WIKI之Cli使用临时目录runtime目录权限777，可用于存放临时生成的文件。路径别名system: 表示平台框架目录，默认为/data/php/framework。webroot: 表示入口脚本文件所在的目录，一般为应用的根目录。application: 表示应用的基础目录，一般为webroot/protected。ext: 表示包含了所有第三方扩展的目录，一般为webroot/protected/extensions。通过使用Mod:getPathOfAlias(), 别名可

18、以被翻译为其相应的路径。例如：system.core.web.CController 会被翻译为/data/php/framework/core/web/CController。类型导入使用别名可以很方便的导入类的定义，如导入webroot/protected/components/ControllerMod:import(application ponents.Controller);同样可以使用目录导入Mod:import(application ponents.*);PHP编码规标签PHP程序可以使用或来界定PHP 代码，在HTML页面中嵌入纯变量时，可以使用这样的形式，不可使用其他的标

19、签变种。纯PHP类文件，文件最后一个?省略。编码PHP代码必须只使用不带BOM的UTF-8。注释单行注释：在语句结尾用双反斜杠”/ “注释多行注释：多行注视以”/*”或“/*”符号开头，以”*/ “符号作为注释结束符。需要生成文档的注释必须是以“/*”开头，以“*/”结尾。主流的IDE开发工具（如Eclipse，Zend）会用不同的颜色来区分下面的几种注释。文件注释/* *（简述，用在索引列表中）* * 详细的功能描述（可略）* * copyright Copyright 2013, 公司名或作者名* author $AUTHOR * version $Id: $FILE_NAME, v $V

20、ERSION $TIME $AUTHOR Exp $ * */类注释/* *（概要）* * 详细的功能描述* * property 类型$prop 属性描述* * author $AUTHOR * package application ponents（参见 HYPERLINK l _路径别名路径别名）* */方法注释/* * 功能描述* * param 类型$fields 描述* * return 类型描述*/属性注释/* * var 类型$fields 描述*/ 其它适当的使用HTML标记语言来美化文档。不管是生成HTML格式还是CHM格式的文档手册，文档工具都是先生成HTML文档页面，所

21、以适当的使用或标签可以美化文档，方便阅读。public和private方法：一般情况下，private私有方法不会暴露给其他开发人员，所以private方法的注释一般以“/*”开头，而public方法以“/*”开头。命名规则Pascal命名法：所有单词第一个字母大写，其他字母小写。Camel命名法(驼峰命名法)：除了第一个单词，所有单词第一个字母大写，其他字母小写。采用英文单词或其组合，便于记忆和阅读，切忌使用汉语拼音来命名。文件类文件的名称和类名一致,如类HelloWorld，相应的文件名为HelloWorld.php配置文件名小写，如config.php嵌套php的view文件使用Came

22、l命名法，第一个字母小写，其他单词的第一个字母大写。如：addApp.php类类命名采用Pascal命名方法，类名应该和文件名相匹配。函数/方法通常方法一般为一个动作或行为动词，函数/方法的命名采用Camel命名方法functionrun()functionrunFast()functiongetBackground()尽量用有意义，描述性的词语来命名用checkForErrors()代替errorCheck()，用dumpDataToFile()代替dataFile()。有时前缀名是有用的：is-含义为问一个关于某样事物的问题。无论何时，当人们看到is就会知道这是一个问题。get-含义为取得

23、一个数值。set-含义为设定一个数值例如：isHitRetryLimit部成员函数命名应该是以“_”开始：function_isUserTicket();变量名用有意义的，描述性的词语来命名变量别用缩写。用name,address,salary等代替nam,addr,sal全局变量以”g_”开头别使用单个字母的变量象i,n,x等.使用index,temp等，用于循环迭代的变量例外：for ($i = 0; $i 必须省略行行长度不可有硬限制。行实际长度不应超过80个字符；较长的行应当被拆分成多个不超过80个字符的后续行。空行可以用来改善可读性和区分相关的代码块。一行不应多于一个语句。缩进每个缩

24、进的单位约定是4个空格的缩进，并且不可使用制表符作为缩进，需每个参与项目的开发人员在编辑器(Eclipse、EditPlus、Zend Studio等)中进行强制设定将TAB转化为4个空格，以防在编写代码时遗忘而造成格式上的不规。控制结构对于控制结构的样式规则概括如下：控制结构关键词之后必须有一个空格左括号之后不可有空格右括号之前不可有空格在右括号和左花括号之间必须有一个空格代码主体必须有一次缩进右花括号必须主体的下一行每个结构的主体必须被括在花括号里。这结构看上去更标准化，并且当加新行的时候可以减少引入错误的可能性。if,elseif, else一个if结构看起来应该像下面这样。注意括号，空

25、格，花括号的位置；并且else和elseif和前一个主体的右花括号在同一行。?phpif ($expr1) / if body elseif ($expr2) / elseif body else / else body;关键词elseif应该替代else if使用以保持所有的控制关键词像一个单词。switch, case一个switch结构看起来应该像下面这样。注意括号，空格和花括号。case语句必须从switch处缩进，并且break关键字（或其他中止关键字）必须和case主体缩进在同级。如果一个非空的case主体往下落空则必须有一个类似/ no break的注释。?phpswitch (

26、$expr) case 0:echo First case, with a break;break;case 1:echo Second case, which falls through;/ no breakcase 2:case 3:case 4:echo Third case, return instead of break;return;default:echo Default case;break;while, do while一个while语句看起来应该像下面这样。注意括号，空格和花括号的位置。?phpwhile ($expr) / structure body同样的，一个do w

27、hile语句看起来应该像下面这样。注意括号，空格和花括号的位置。?phpdo / structure body; while ($expr);for一个for语句看起来应该像下面这样。注意括号，空格和花括号的位置。?phpfor ($i = 0; $i 10; $i+) / for bodyforeach一个foreach语句看起来应该像下面这样。注意括号，空格和花括号的位置。 $value) / foreach bodytry, catch一个try catch语句看起来应该像下面这样。注意括号，空格和花括号的位置。”结束标记去掉?phpclass Foobody一个类的extends和im

28、plements关键词必须和类名在同一行。class ClassName extends ParentClass implements ArrayAccess, Countable/ constants, properties, methodsimplements一个列表可以被拆分为多个有一次缩进的后续行。如果这么做，列表的第一项必须要放在下一行，并且每行必须只有一个接口。class ClassName extends ParentClass implementsArrayAccess,Countable,Serializable/ constants, properties, methods

29、属性所有的属性必须声明可见性。var关键词不可用来声明属性。一个语句不可声明多个属性。属性名称可以使用单个下划线作为前缀来表明保护或私有的可见性。class ClassNamepublic $foo = null;private $_bar = 1;方法所有的方法必须声明可见性。方法名不应只使用单个下划线来表明是保护或私有的可见性。方法名在声明之后不可跟随一个空格。左花括号必须放在下面自成一行，并且右花括号必须放在方法主体的下面自成一行。左括号后面不可有空格，右括号前面不可有空格。一个方法定义看来应该像下面这样。注意括号，逗号，空格和花括号：在参数列表中，逗号之前不可有空格，逗号之后必须要有一

30、个空格。方法中有默认值的参数必须放在参数列表的最后面。class ClassNamepublic function fooBarBaz($arg1, &$arg2, $arg3 = )/ method body参数列表可以被分为多个有一次缩进的多个后续行。如果这么做，列表的第一项必须放在下一行，并且每行必须只放一个参数。当参数列表被分为多行，右括号和左花括号必须夹带一个空格放在一起自成一行。class ClassNamepublic function aVeryLongMethodName(ClassTypeHint $arg1,&$arg2,array $arg3 = ) / method

31、body如果存在，abstract和final声明必须放在可见性声明前面。如果存在，static声明必须跟着可见性声明。数据库命名规命名规数据库的所有表(Table)、视图(View)、索引(Index)、触发器(Trigger)、函数(Function)和存储过程(Store Procedure)均应遵循以下命名规。命名统一用大写命名只能由小写字母和数字构成，并且只能是以小写字母打头命名应采用能够准确反映其中文含义的英文单词或英文单词缩写构成，避免出现英文单词和汉语拼音混用的局面命名长度不可以超过25个字符（表名尽量保持在20个字符的长度，然后再其上建立索引、主键、触发器等等的时候，便于加扩

32、展信息）名称的各部分之间以_(下划线)连接字段如有一样定义，应该用一样命名命名应避免用关键字，参见附录一关键字列表实体命名实体(包括库表、视图、函数和索引等)命名结构如下：prefix_module_body_suffix为前缀名，表示数据库对象的类型为模块名，按应用模块进行分类，为可选项为主体名，应该能够清楚地说明对象的含义是后缀名，提供特效的含义，比如在该对象需分表存放时使用，如按月分开存放的表，为可选项。前缀命名前缀数据库对象t表(Table)v视图(View)tri触发器(Trigger)p存储过程(Procedure)tt临时表(Temporary Table)idx索引(Index

33、)uk唯一索引（Unique Index）pk主键(Primary Key)fk外键(Foreign Key)f函数（Function）后缀命名后缀定义_HIS历史表_LOG流水表_MAP对照表_REL关系表_YYYYMMDD因数据量庞大，需按日分开存放的表_YYYYMM因数据量庞大，需按月分开存放的表字段命名字段命名结构如下:prefix_body_suffix为前缀名，为必填项，必须为“f”。为主体名，应该能够清楚地说明对象的含义是后缀名，提供特效的含义，为可选项。后缀命名以下是一些特别的后缀，代表了这个字段特效的含义。在其他的情况，应避免使用以下的后缀。后缀定义_DESC参数表的描叙字段

34、一般来讲是VARCHAR(255)_FLAG只可能是True或False的字段一般来讲是TINYINT(1)_ID标识字段，一般来讲是INT（11）_TYPE类型字段，一般来讲是CHAR(1)字段类型一般来说， 在保证正确性的前提下，尽量使用最小的数据类型来存储和表示数据。 小的数据类型一般比大的更快，因为小的数据类型占用的磁盘空间， 存和cup缓存都相对小，需要的cpu处理也要相对少; 这个原则很重要， 但是设计的时候也不要低估需要存储的数据的数据围。简单的数据类型需要的cup处理周期更少，比如：对整数的处理比字符串处理更容易， 因为字符集和排序规则使得字符串比较复杂化了， 两个典型例子是：

35、 使用mysql的嵌数据类型来存储日期和时间而不是字符串，使用整数存储Ip地址而不是字符串。数值类型非万不得已不要使用DOUBLE，不仅仅只是存储长度的问题，同时还会存在精确性的问题。固定精度的小数，也不建议使用DECIMAL，建议乘以固定倍数转换成整数存储，可以大大节省存储空间，且不会带来任何附加维护成本。对于整数的存储，在数据量较大的情况下，建议区分开 TINYINT / INT / BIGINT 的选择，因为三者所占用的存储空间也有很大的差别，能确定不会使用负数的字段，建议添加unsigned定义。字符类型非万不得已不要使用 TEXT 数据类型，其处理方式决定了他的性能要低于char或者

36、是varchar类型的处理。定长字段，建议使用 CHAR 类型，不定长字段尽量使用 VARCHAR，且仅仅设定适当的最大长度，而不是非常随意的给一个很大的最大长度限定，因为不同的长度围，MySQL也会有不一样的存储处理。时间类型尽量使用TIMESTAMP类型，因为其存储空间只需要 DATETIME 类型的一半。对于只需要精确到某一天的数据类型，建议使用DATE类型，因为他的存储空间只需要3个字节，比TIMESTAMP还少。不建议通过INT类型类存储一个unix timestamp 的值，因为这太不直观，会给维护带来不必要的麻烦，同时还不会带来任何好处。ENUM&SET对于状态字段，可以尝试使用

37、 ENUM 来存放，因为可以极大的降低存储空间。如果是存放可预先定义的属性数据，可以尝试使用SET类型，即使存在多种属性，同样可以游刃有余，同时还可以节省不小的存储空间。LOB 类型强烈反对在数据库中存放 LOB 类型数据表结构设计适度冗余不需要一定遵守式理论，适度的冗余，让Query尽量减少Join尽量使用NOT NULL尽可能把字段定义成NOT NULL，许多表包含一些字段允许空的字段，即使应用需求不需要存储NULL的数据，因为允许字段为NULL是缺省的。允许NULL的字段会占用掉更多的存储空间和花掉更多的cpu处理，当为一个可为空的字段建立索引时， 需要为每项分配一个额外的字节。即使遇到不需要存储值到某个字段，也应当考虑不使用NULL，而是考虑使用0，一个特殊值或者空串来代替。索引唯一确定一条记录的一个字段或多个字段要建立主键或者唯一索引，不能唯一确定一条记录，为了提高查询效率建普通索引对于取值不能重复，经常作为查询条件的字段，应该建唯一索引(主键默认唯一索引)，并且将查询条件中该字段的条件置于第一个位置。没有必要再建立与该字段有关的联合索引。对于经常查询的字段，其值不唯一，也应该考虑建立普通索引，查询语句中该字段条件置于第一个位置，对联合索引处理的方法同样。需要联合索引(或联合主键)的数据库要注意索引的顺序。SQL语句中的匹配条件也要跟索引的顺序保持一