数据库命名规范.doc

OMG网络媒体技术部 海豹平台开发规范v1.0海豹平台开发规范v1.0腾讯科技（深圳）有限公司*版本信息&保密等级版本更改日期更改要点说明编制审核批准V1.02013/12/24新建wilsonwsongV1.12013/12/26修订rusherding文档保密等级：机密 内部 公开目 录海豹平台开发规范V1.011 引言51.1 定义及缩略语51.2 参考文档51.3 目的51.4 适用范围51.5 标准化作用52 目录结构规范62.1 框架路径62.2 应用目录结构62.2.1 配置config72.2.2 控制器controllers72.2.3 模型models72.2.4 视图views82.2.5 国际化messages82.2.6 组件components82.2.7 命令commands82.2.8 临时目录runtime82.3 路径别名82.3.1 类型导入83 PHP编码规范93.1 标签93.2 编码93.3 注释93.3.1 文件注释93.3.2 类注释103.3.3 方法注释103.3.4 属性注释113.3.5 其它113.4 命名规则113.4.1 文件113.4.2 类123.4.3 函数/方法123.4.4 变量名123.4.5 常量名123.5 书写规则133.5.1 文件133.5.2 行133.5.3 缩进133.5.4 控制结构133.5.5 运算符163.5.6 引号163.5.7 关键词173.5.8 函数173.5.9 类173.5.10 属性183.5.11 方法184 数据库命名规范204.1 命名规范204.2 实体命名204.2.1 前缀命名204.2.2 后缀命名214.3 字段命名214.3.1 后缀命名224.4 字段类型224.4.1 数值类型224.4.2 字符类型234.4.3 时间类型234.4.4 ENUM&SET234.4.5 LOB 类型234.5 表结构设计244.5.1 适度冗余244.5.2 尽量使用NOT NULL244.5.3 索引245 附件245.1 附录一：MYSQL保留字241 引言1.1 定义及缩略语缩略词说明海豹平台运维中心提供的研发平台，提供框架、公共基础组件、公共业务组件加速业务的日常研发工作1.2 参考文档海豹平台WIKI：1.3 目的本规范由编程原则组成，融合并提炼了开发人员长时间积累下来的成熟经验，意在帮助形成良好一致的编程风格。以达到事半功倍的效果，如果有需要本文档会不定期更新。 1.4 适用范围如无特殊说明，以下规则要求完全适用于基于海豹平台框架开发的应用，同时也可大部分适用于部门其他PHP项目。1.5 标准化作用当一个软件项目尝试着遵守公共一致的标准时，可以使参与项目的开发人员更容易了解项目中的代码、弄清程序的状况。使新的参与者可以很快的适应环境，防止部分参与者出于节省时间的需要，自创一套风格并养成终生的习惯，导致其它人在阅读时浪费过多的时间和精力。而且在一致的环境下，也可以减少编码出错的机会。缺陷是由于每个人的标准不同，所以需要一段时间来适应和改变自己的编码风格，暂时性的降底了工作效率。从使项目长远健康的发展以及后期更高的团队工作效率来考虑暂时的工作效率降低是值得的，也是必须要经过的一个过程。标准不是项目成功的关键，但可以帮助我们在团队协作中有更高的效率并且更加顺利的完成既定的任务。 1) 程序员可以了解任何代码，弄清程序的状况 2) 新人可以很快的适应环境 3) 防止新接触PHP的开发出于节省时间的需要，自创一套风格并养成终生的习惯 4) 防止新接触PHP的开发一次次的犯同样的错误 5) 在一致的环境下，可以减少犯错的机会 2 目录结构规范2.1 框架路径框架引用路径必须采用绝对路径，托管的开发、测试和正式环境必须为：/data/php/framework2.2 应用目录结构应用需要严格参考以下目录安排代码位置：webroot/ index.php Web 应用入口脚本文件 index-test.php 功能测试使用的入口脚本文件 assets/ 包含公开的资源文件 css/ 包含 CSS 文件 images/ 包含图片文件 themes/ 包含应用主题 protected/ 包含受保护的应用文件 modc 命令行脚本 modc.bat Windows 下的命令行脚本 modc.php 命令行 PHP 脚本 commands/ 包含自定义的 modc 命令 components/ 包含可重用的用户组件 config/ 包含配置文件 controllers/ 包含控制器的类文件 SiteController.php 默认控制器的类文件 extensions/ 包含第三方扩展 messages/ 包含翻译过的消息(i8n相关) models/ 包含模型的类文件 runtime/ 包含临时生成的文件 tests/ 包含测试脚本 views/ 包含控制器的视图和布局文件 layouts/ 包含布局视图文件 main.php 所有视图的默认布局site/ 包含 site 控制器的视图文件 system/ 包含系统视图文件2.2.1 配置config存放应用配置目录，具体参考WIKI人口脚本2.2.2 控制器controllers存放控制逻辑的类目录，具体参考WIKI控制器2.2.3 模型models存放模型定义的类目录，具体参考WIKI模型2.2.4 视图views存放视图文件的目录，具体目录参考WIKI视图2.2.5 国际化messages存放国际化定义文件的目录2.2.6 组件components存放组件的类目录，具体目录参考WIKI组件2.2.7 命令commands存放Console命令的类目录，具体目录参考WIKI之Cli使用2.2.8 临时目录runtime目录权限777，可用于存放临时生成的文件。2.3 路径别名1) system: 表示平台框架目录，默认为/data/php/framework。2) webroot: 表示入口脚本文件所在的目录，一般为应用的根目录。3) application: 表示应用的基础目录，一般为webroot/protected。4) ext: 表示包含了所有第三方扩展的目录，一般为webroot/protected/extensions。通过使用 Mod:getPathOfAlias(), 别名可以被翻译为其相应的路径。例如：system.core.web.CController 会被翻译为 /data/php/framework/core/web/CController。2.3.1 类型导入使用别名可以很方便的导入类的定义，如导入webroot/protected/components/ControllerMod:import(ponents.Controller);同样可以使用目录导入Mod:import(ponents.*);3 PHP编码规范3.1 标签PHP程序可以使用或来界定 PHP 代码，在HTML页面中嵌入纯变量时，可以使用这样的形式，不可使用其他的标签变种。纯PHP类文件，文件最后一个?省略。3.2 编码PHP代码必须只使用不带BOM的UTF-8。3.3 注释1) 单行注释：在语句结尾用双反斜杠”/ “注释2) 多行注释：多行注视以”/*”或“/*”符号开头，以”*/ “符号作为注释结束符。需要生成文档的注释必须是以“/*”开头，以“*/”结尾。主流的IDE开发工具（如Eclipse，Zend）会用不同的颜色来区分下面的几种注释。3.3.1 文件注释/* *（简述，用在索引列表中） * * 详细的功能描述（可略） * * copyright Copyright© 2013, 公司名或作者名 * author $AUTHOR * version $Id: $FILE_NAME, v $VERSION $TIME $AUTHOR Exp $ * */3.3.2 类注释/* *（概要） * * 详细的功能描述* * property 类型 $prop 属性描述* * author $AUTHOR * package ponents（参见路径别名）* */3.3.3 方法注释/* * 功能描述* * param 类型 $fields 描述 * * return 类型 描述*/3.3.4 属性注释/* * var 类型 $fields 描述 */ 3.3.5 其它1) 适当的使用HTML标记语言来美化文档。不管是生成HTML格式还是CHM格式的文档手册，文档工具都是先生成HTML文档页面，所以适当的使用或标签可以美化文档，方便阅读。2) public和private方法：一般情况下，private私有方法不会暴露给其他开发人员，所以private方法的注释一般以“/*”开头，而public方法以“/*”开头。3.4 命名规则Pascal命名法：所有单词第一个字母大写，其他字母小写。Camel命名法(驼峰命名法)：除了第一个单词，所有单词第一个字母大写，其他字母小写。采用英文单词或其组合，便于记忆和阅读，切忌使用汉语拼音来命名。3.4.1 文件1) 类文件的名称和类名一致,如类HelloWorld，相应的文件名为HelloWorld.php2) 配置文件名小写，如 config.php3) 嵌套php的view文件使用Camel命名法，第一个字母小写，其他单词的第一个字母大写。如：addApp.php3.4.2 类类命名采用Pascal命名方法，类名应该和文件名相匹配。3.4.3 函数/方法通常方法一般为一个动作或行为动词，函数/方法的命名采用Camel命名方法functionrun()functionrunFast()functiongetBackground()尽量用有意义，描述性的词语来命名用checkForErrors()代替errorCheck()，用dumpDataToFile()代替dataFile()。有时前缀名是有用的：is-含义为问一个关于某样事物的问题。无论何时，当人们看到is就会知道这是一个问题。get-含义为取得一个数值。set-含义为设定一个数值例如：isHitRetryLimit内部成员函数命名应该是以“_”开始：function_isUserTicket();3.4.4 变量名1) 用有意义的，描述性的词语来命名变量2) 别用缩写。用name,address,salary等代替nam,addr,sal全局变量以”g_”开头3) 别使用单个字母的变量象i,n,x等.使用index,temp等，用于循环迭代的变量例外：for ($i = 0; $i 必须省略3.5.2 行1) 行长度不可有硬限制。2) 行实际长度不应超过80个字符；较长的行应当被拆分成多个不超过80个字符的后续行。3) 空行可以用来改善可读性和区分相关的代码块。4) 一行不应多于一个语句。3.5.3 缩进每个缩进的单位约定是4个空格的缩进，并且不可使用制表符作为缩进，需每个参与项目的开发人员在编辑器(Eclipse、EditPlus、Zend Studio等)中进行强制设定将TAB转化为4个空格，以防在编写代码时遗忘而造成格式上的不规范。 3.5.4 控制结构对于控制结构的样式规则概括如下：1) 控制结构关键词之后必须有一个空格2) 左括号之后不可有空格3) 右括号之前不可有空格4) 在右括号和左花括号之间必须有一个空格5) 代码主体必须有一次缩进6) 右花括号必须主体的下一行每个结构的主体必须被括在花括号里。这结构看上去更标准化，并且当加新行的时候可以减少引入错误的可能性。3.5.4.1 if,elseif, else一个if结构看起来应该像下面这样。注意括号，空格，花括号的位置；并且else和elseif和前一个主体的右花括号在同一行。?phpif ($expr1) / if body elseif ($expr2) / elseif body else / else body;关键词elseif应该替代else if使用以保持所有的控制关键词像一个单词。3.5.4.2 switch, case一个switch结构看起来应该像下面这样。注意括号，空格和花括号。case语句必须从switch处缩进，并且break关键字（或其他中止关键字）必须和case主体缩进在同级。如果一个非空的case主体往下落空则必须有一个类似/ no break的注释。?phpswitch ($expr) case 0: echo First case, with a break; break; case 1: echo Second case, which falls through; / no break case 2: case 3: case 4: echo Third case, return instead of break; return; default: echo Default case; break;3.5.4.3 while, do while一个while语句看起来应该像下面这样。注意括号，空格和花括号的位置。?phpwhile ($expr) / structure body同样的，一个do while语句看起来应该像下面这样。注意括号，空格和花括号的位置。?phpdo / structure body; while ($expr);3.5.4.4 for一个for语句看起来应该像下面这样。注意括号，空格和花括号的位置。?phpfor ($i = 0; $i 10; $i+) / for body3.5.4.5 foreach一个foreach语句看起来应该像下面这样。注意括号，空格和花括号的位置。 $value) / foreach body3.5.4.6 try, catch一个try catch语句看起来应该像下面这样。注意括号，空格和花括号的位置。”结束标记去掉?phpclass Foo body4) 一个类的extends和implements关键词必须和类名在同一行。class ClassName extends ParentClass implements ArrayAccess, Countable / constants, properties, methods5) implements一个列表可以被拆分为多个有一次缩进的后续行。如果这么做，列表的第一项必须要放在下一行，并且每行必须只有一个接口。class ClassName extends ParentClass implements ArrayAccess, Countable, Serializable / constants, properties, methods3.5.10 属性1) 所有的属性必须声明可见性。2) var关键词不可用来声明属性。3) 一个语句不可声明多个属性。4) 属性名称可以使用单个下划线作为前缀来表明保护或私有的可见性。class ClassNamepublic $foo = null;private $_bar = 1;3.5.11 方法1) 所有的方法必须声明可见性。2) 方法名不应只使用单个下划线来表明是保护或私有的可见性。3) 方法名在声明之后不可跟随一个空格。左花括号必须放在下面自成一行，并且右花括号必须放在方法主体的下面自成一行。左括号后面不可有空格，右括号前面不可有空格。4) 一个方法定义看来应该像下面这样。 注意括号，逗号，空格和花括号：5) 在参数列表中，逗号之前不可有空格，逗号之后必须要有一个空格。6) 方法中有默认值的参数必须放在参数列表的最后面。class ClassName public function fooBarBaz($arg1, &$arg2, $arg3 = ) / method body 7) 参数列表可以被分为多个有一次缩进的多个后续行。如果这么做，列表的第一项必须放在下一行，并且每行必须只放一个参数。8) 当参数列表被分为多行，右括号和左花括号必须夹带一个空格放在一起自成一行。class ClassName public function aVeryLongMethodName( ClassTypeHint $arg1, &$arg2, array $arg3 = ) / method body 9) 如果存在，abstract和final声明必须放在可见性声明前面。10) 如果存在，static声明必须跟着可见性声明。4 数据库命名规范4.1 命名规范数据库的所有表(Table)、视图(View)、索引(Index)、触发器(Trigger)、函数(Function)和存储过程(Store Procedure)均应遵循以下命名规范。1) 命名统一用大写2) 命名只能由小写字母和数字构成，并且只能是以小写字母打头3) 命名应采用能够准确反映其中文含义的英文单词或英文单词缩写构成，避免出现英文单词和汉语拼音混用的局面4) 命名长度不可以超过25个字符（表名尽量保持在20个字符的长度，然后再其上建立索引、主键、触发器等等的时候，便于加扩展信息）5) 名称的各部分之间以_(下划线)连接6) 字段如有相同定义，应该用相同命名7) 命名应避免用关键字，参见附录一关键字列表4.2 实体命名实体(包括库表、视图、函数和索引等)命名结构如下： prefix_module_body_suffix1) 为前缀名，表示数据库对象的类型2) 为模块名，按应用模块进行分类，为可选项3) 为主体名，应该能够清楚地说明对象的含义4) 是后缀名，提供特效的含义，比如在该对象需分表存放时使用，如按月分开存放的表，为可选项。4.2.1 前缀命名前缀数据库对象t表(Table)v视图(View)tri触发器(Trigger)p存储过程(Procedure)tt临时表(Temporary Table)idx索引(Index)uk唯一索引（Unique Index）pk主键(Primary Key)fk外键(Foreign Key)f函数（Function）4.2.2 后缀命名后缀定义_HIS历史表_LOG流水表_MAP对照表_REL关系表_YYYYMMDD因数据量庞大，需按日分开存放的表_YYYYMM因数据量庞大，需按月分开存放的表4.3 字段命名字段命名结构如下: prefix_body_suffix1) 为前缀名，为必填项，必须为“f”。2) 为主体名，应该能够清楚地说明对象的含义3) 是后缀名，提供特效的含义，为可选项。4.3.1 后缀命名以下是一些特别的后缀，代表了这个字段特效的含义。在其他的情况，应避免使用以下的后缀。后缀定义_DESC 参数表内的描叙字段 一般来讲是VARCHAR(255)_FLAG 只可能是True或False的字段 一般来讲是TINYINT(1)_ID 标识字段，一般来讲是INT（11）_TYPE 类型字段，一般来讲是CHAR(1)4.4 字段类型一般来说， 在保证正确性的前提下，尽量使用最小的数据类型来存储和表示数据。 小的数据类型一般比大的更快，因为小的数据类型占用的磁盘空间， 内存和cup缓存都相对小，需要的cpu处理也要相对少; 这个原则很重要， 但是设计的时候也不要低估需要存储的数据的数据范围。简单的数据类型需要的cup处理周期更少，比如：对整数的处理比字符串处理更容易， 因为字符集和排序规则使得字符串比较复杂化了， 两个典型例子是： 使用mysql的内嵌数据类型来存储日期和时间而不是字符串，使用整数存储Ip地址而不是字符串。4.4.1 数值类型1) 非万不得已不要使用DOUBLE，不仅仅只是存储长度的问题，同时还会存在精确性的问题。2) 固定精度的小数，也不建议使用DECIMAL，建议乘以固定倍数转换成整数存储，可以大大节省存储空间，且不会带来任何附加维护成本。3) 对于整数的存储，在数据量较大的情况下，建议区分开 TINYINT / INT / BIGINT 的选择，因为三者所占用的存储空间也有很大的差别，能确定不会使用负数的字段，建议添加unsigned定义。4.4.2 字符类型1) 非万不得已不要使用 TEXT 数据类型，其处理方式决定了他的性能要低于char或者是varchar类型的处理。2) 定长字段，建议使用 CHAR 类型，不定长字段尽量使用 VARCHAR，且仅仅设定适当的最大长度，而不是非常随意的给一个很大的最大长度限定，因为不同的长度范围，MySQL也会有不一样的存储处理。4.4.3 时间类型1) 尽量使用TIMESTAMP类型，因为其存储空间只需要 DATETIME 类型的一半。2) 对于只需要精确到某一天的数据类型，建议使用DATE类型，因为他的存储空间只需要3个字节，比TIMESTAMP还少。3) 不建议通过INT类型类存储一个unix timestamp 的值，因为这太不直观，会给维护带来不必要的麻烦，同时还不会带来任何好处。4.4.4 ENUM&SET1) 对于状态字段，可以尝试使用 ENUM 来存放，因为可以极大的降低存储空间。2) 如果是存放可预先定义的属性数据，可以尝试使用SET类型，即使存在多种属性，同样可以游刃有余，同时还可以节省不小的存储空间。4.4.5 LOB 类型强烈反对在数据库中存放 LOB 类型数据4.5 表结构设计4.5.1 适度冗余不需要一定遵守范式理论，适度的冗余，让Query尽量减少Join4.5.2 尽量使用NOT NULL尽可能把字段定义成NOT NULL，许多表包含一些字段允许空的字段，即使应用需求不需要存储NULL的数据，因为允许字段为NULL是缺省的。允许NULL的字段会占用掉更多的存储空间和花掉更多的cpu处理，当为一个可为空的字段建立索引时， 需要为每项分配一个额外的字节。即使遇到不需要存储值到某个字段，也应当考虑不使用NULL，而是考虑使用0，一个特殊值或者空串来代替。4.5.3 索引1) 唯一确定一条记录的一个字段或多个字段要建立主键或者唯一索引，不能唯一确定一条记录，为了提高查询效率建普通索引2) 对于取值不能重复，经常作为查询条件的字段，应该建唯一索引(主键默认唯一索引)，并且将查询条件中该字段的条件置于第一个位置。没有必要再建立与该字段有关的联合索引。3) 对于经常查询的字段，其值不唯一，也应该考虑建立普通索引，查询语句中该字段条件置于第一个位置，对联合索引处理的方法同样。4) 需要联合索引(或联合主键)的数据库要注意索引的顺序。SQL语句中的匹配条件也要跟索引的顺序保持一致。5 附件5.1 附录一：MYSQL保留字保留字保留字保留字ADDALLALTERANALYZEANDASASCAUTO_INCREMENTBDBBEFOREBERKELEYDBBETWEENBIGINTBINARYBLOBBOTHBTREEBYCASCADECASECHANGECHARCHARACTERCHECKCOLLATECOLUMNCOLUMNSCONSTRAINTCREATECROSSCURRENT_DATECURRENT_TIMECURRENT_TIMESTAMPDATABASEDATABASESDAY_HOURDAY_MINUTEDAY_SECONDDECDECIMALDEFAULTDELAYEDDELETEDESCDESCRIBEDISTINCTDISTINCTROWDIVDOUBLEDROPELSEENCLOSEDERRORSESCAPEDEXISTSEXPLAINFALSEFIELDSFLOATFORFORCEFOREIGNFROMFULLTEXTFUNCTIONGRANTGROUPHASHHAVINGHIGH_PRIORITYHOUR_MINUTEHOUR_SECONDIFIGNOREININDEXINFILEINNERINNODBINSERTINTINTEGERINTERVALINTOISJOINKEYKEYSKILLLEADINGLEFTLIKELIMITLINESLOADLOCALTIMELOCALTIMESTAMPLOCKLONGLONGBLOBLONGTEXTLOW_PRIORITYMASTER_SERVER_IDMATCHMEDIUMBLOBMEDIUMINTMEDIUMTEXTMIDDLEINTMINUTE_SECONDMODMRG_MYISAMNATURALNOTNULLNUMERICONOPTIMIZEOPTIONOPTIONALLYORORDEROUTEROUTFILEPRECISIONPRIMARYPRIVILEGESPROCEDUREPURGEREADREALREFERENCESREGEXPRENAMEREPLACEREQUIRERESTRICTRETURNSREVOKERIGHTRLIKERTREESELECTSETSHOWSMALLINTSOMESONAMESPATIALSQL_BIG_RESULTSQL_CALC_FOUND_ROWSSQL_SMALL_RESULTSSLSTARTINGSTRAIGHT_JOINSTRIPEDTABLETABLESTERMINATEDTHENTINYBLOBTINYINTTINYTEXTTOTRAILINGTRUETYPESUNIONUNIQUEUNLOCKUNSIGNEDUPDATEUSAGEUSEUSER_RESOURCESUSINGVALUESVARBINARYVARCHARVARCHARACTERVARYINGWARNINGSWHENWHEREWITHWRITEXORYEAR_MONTHZEROFILL