TAE
TAE-Java应用开发指南
一、术语约定
为统一共识，满足多环境管理和服务托管，在此我们对文档和相关系统中牵涉到的相关名词进行解释：
1、基础术语：
容器：是应用服务器中位于组件和平台之间的接口集合，提供运行应用的环境（如：Tomcat、Jetty、JBoss等）。
IDE：集成开放环境（如：Eclipse、IDEA等），是用于提供程序开发环境的应用程序，一般包括代码编辑器、编译器、调试器和图形用户界面工具
JDNI： Java 命名与目录接口，主要提供应用程序所需要资源上命名与目录服务；通过容器中配置JNDI参数，定义一个数据源；然后，在程序中，通过数据源名称引用数据源从而访问后台数据库
Maven：是基于项目对象模型(POM)，可以通过一小段描述信息来管理项目的构建，报告和文档的软件项目管理工具。
Ant：是一种基于Java的build工具。
2、淘宝名词：
TOP：淘宝开放平台，是基于淘宝各类电子商务业务的开放平台，提供外部合作伙伴参与服务淘宝用户的各类原材料，例如API、账号体系、数据安全等，可以理解为连接淘宝的大数据与ISV的大门；
TAE-SDK：线下容器，主要为了便于ISV的线下测试而推出的开发辅助工具；
基础服务：特指数据库、缓存、文件存储、FetchUrl、消息队列、日志、RPC等。
二、环境准备
1、JDK下载
请到 官方网址 下载JDK6；安装JDK，并在高级系统设置中设置环境变量JAVA_HOME为安装的根目录，PATH 添加路径%JAVA_HOME%\bin
2、TAE-SDK下载
TAE-SDK是进行TAE应用线下调试的环境，按开发语言可以分为Java和php两个版本，点击下载。
3、相关系统
TAE Work Station：是进行应用上传、部署、发布和数据库、日志等管理的工作台；
TAE 构建系统：是使用源代码方式进行应用部署时所使用的构建系统，对ISV来说透明；
三、开发工具
开发工具对于开发人员来说至关重要，为降低开发难度和利于问题排查，我们现在对开发工具的选取提供以下建议，仅供参考。
1、IDE
现在市场上有很多进行JAVA应用开发的IDE，TAE对这一块并没有做过多限制，但鉴于社区和大量的操作手册都是基于Eclipse和IDEA，所以为了便于出错排查，我们建议您选择Eclipse和IDEA。
2、构建工具
TAE的构建系统提供了Maven和Ant两种构建方式，如果你使用源代码构建部署方式，那么请使用Maven和Ant两款工具进行JAVA应用的构建；出于安全考虑，我们对Maven构建和Ant构建进行了限制，具体的限制请参考Q&A的《构建约束》。如果您使用的是war包上传方式，那么，对使用什么样的构建工具并没有限制。
3、版本管理
TAE构建系统获取源代码的方式有两种方式：Git和SVN，如果你使用的是源代码构建部署方式，那么请使用Git或SVN进行版本管理；另外，由于我们的线上和线下环境还存在差异，所以我们建议您使用版本管理系统的分支开发模型，用于线上、线下环境的切换。
四、开发模型
由于线下容器和线上容器还存在细微差异（主要是服务配置的差异），所以我们建议大家采用分支开发模型（可通过版本控制系统实现），用于线上、线下环境的切换。针对不同的业务类型，可选的分支开发模型有以下几种（以Git为例）：
1、SDK-线上开发模型
如果选取这种开发模型，一开始的开发调试环境即为TAE-SDK，在相对稳定后，可生成一个master分支到线上进行测试；线上测试无问题后，可以继续在TAE-SDK分支进行开发，如果需要切换到线上进行测试，只要将当前的开发分支—TAE-SDK分支合并到master分支即可。这样，即便于开发，又便于维持master分支的稳定。
适合此种分支的业务类型一般是前后台的限制较多，与传统的开发模式有较大差异的业务，如U站业务和爱淘宝业务，其前端有caja和套头套尾，所以本地开发然后切换的话成本会较大，适合直接使用SDK作为线下开发调试环境。
2、本地-（SDK）-线上开发模型
如果选取这种开发模型，一开始的开发调试环境即为本地，在相对稳定后，可生成一个master分支到线上进行测试（可以先在TAE-SDK上测试下某些切换是否可行）；线上测试无问题后，可以继续在本地分支进行开发，如果需要切换到线上进行测试，只要将当前的开发分支—本地分支合并到master分支即可。这样，即便于开发，又便于维持master分支的稳定。
适合此种分支的业务类型一般是前后台的限制较少，与传统的开发模式没有太大的差异或者是必须到线上才能进行测试的业务（TAE-SDK无法模拟前台效果），如微淘插件开放业务，其测试环境大部分都位于线上，而且从本地切换到线上只是服务的切换。
五、调试应用
开发者调试应用，一般分为本地调试、SDK调试、线上调试三个环境。下面分别叙述三个调试环境的内容。
1、本地调试
本地调试是指我们正常开发模式下的调试，是每个开发者都熟悉的开放方式，这里不再详述。
2、SDK调试
ISV可以直接通过TAE-SDK进行线下调试，线下调试的具体过程如下：
代码打包
把web应用代码打成war包，并放到Tae-tomcat\webapp\目录下。
启动容器
运行Tae-tomcat\bin\startup.bat(startup.sh)启动容器（即应用服务器）。
web页面访问
访问127.0.0.1:8080\[你应用名称]\[页面地址]，访问你应用的web页面。
远程调试
因为我们的TAE应用运行在TAE容器中，所以如果需要调试的话，需要设置IDE的远程调试环境，以下将演示我们的远程调试过程：
A、添加远程调试实例：
B、设置远程调试实例的参数
注意：这里的端口可以在你的TAE启动容器时看到（如无特殊设置，一般是8787）：
3、线上调试
线上调试只能通过日志进行，现有的日志查询可以查看应用日志和容器日志，在线下测试无问题并部署成功后，如果发现应用无法访问，请首先检查容器日志，如果容器无异常和错误再去检查应用日志。
六、部署应用
TAE系统提供了两种部署应用的方式，一是将打包好的war包上传，二是使用TAE的构建系统直接从源代码进行构建并自动部署；ISV可以根据自己的习惯，选择合适的方式。
1、打包上传
在本地使用Maven或Ant将项目打为war包，然后直接使用TAE work station控制台进行代码的上传，代码上传后，系统会扫描和自动部署。
2、Git构建部署
从源代码开始部署应用主要经过三个过程：代码编译、代码扫描和应用部署。具体操作如下：
点击编译按钮打开编译面板，选择仓库方式，填入用户名和密码后，点击编译&部署按钮进行应用的编译和部署，待完成后可以点击访问应用按钮进行应用的访问；
3、SVN构建部署
请参考Git构建部署
七、应用上线
1、发布应用
在测试环境下调试应用OK后，点击发布按钮，就可以将应用发布到正式环境了。
2、访问应用
在测试环境和正式环境下都可以访问应用，选择相应的环境，然后点击访问应用按钮即可实现应用的访问。
3、应用上架
发布应用成功后，根据不同的业务类型有不同的上架规则，ISV可以根据具体的业务上架规联系运营进行应用的上架。
4、应用更新
ISV可以通过重新部署应用进行应用的更新，在上传应用到测试环境后可以通过点击发布按钮上传至正式环境来实现应用的更新。
八、基础服务
1、基础服务简介
1）、目前TAE提供的基础服务如下面列表所示：
服务名称 |
说明 |
CacheService（缓存服务） |
目前还没有加上原子性的操作，如compareAndSet； 后期有实现场景再加上； |
StoreService（存储服务） |
还没有加入面向Stream的API，如saveFile(InputStream file)； 暂不考虑加入目录相关的操作，如moveDir(from, to)； 暂没有加list目录下文件的API； |
FetchUrlService（对外Http访问服务） |
目前只提供了简单用法的API，可以完成功能。 完整的使用场景下，需要能对HTTP进行完整的控制，如超 时、HTTP头、自动重定向。这要完整Http模型，会让使用复杂化，后 期考虑再加上。 |
MessageService（消息队列服务） |
消息队列以queue为单位，支持peer to peer模式； 暂不支持发布/订阅，暂不保证消息投递顺序； 消息保证投递，但异常情况下可能会出现重复消费； 创建queue默认超时时间无限长（消息处理不会超时）； |
DataSource(JDBC)（数据库服务） |
数据库服务； |
日志服务 |
|
RPC服务 |
|
2）、线上服务使用
在线上运行环境中，用户可以无需关心实际的服务地址信息，直接通过服务别名来获取服务。
3）、线下服务使用
在线下SDK中，用户需要少许配置，以便在本地开发环境中模拟服务调用。
2、基础服务包引入和调用
1）引入方式
请把services-api.jar和services-jae-api.jar加到项目的classpath中。
2）调用方式（以链接数据库DataSource为例）
Spring配置方式：
1. <bean id="datasource" class="com.alibaba.appengine.api.ds.DataSourceFactory" factory-method = "getDataSource">
直接导入方式：
1. import com.alibaba.appengine.api.ds.DataSourceFactory;
2. DataSource ds = DataSourceFactory.getDataSource();
九、数据获取
1、用户信息获取
利用TAE容器所提供的api可以轻松获得用户的信息，以下以获取用户的Nick为例（注：此处获取的是用户的混淆Nick，而非真实Nick）
1. Import com.alibaba.appengine.jae.model.TaobaoTinyUser;
2. String mixUserNick ="淘宝用户混淆Nick";
3. //获取当前登录用户,session定义和获取方式跟普通项目一样
4. TaobaoTinyUser taobaoTinyUser = (TaobaoTinyUser) session.getAttribute(TaobaoTinyUser.SESSION_KEY);
5. if(taobaoTinyUser!=null){
6. mixUserNick = taobaoTinyUser.getTaobaoUserNick();
7. }
2、TOP授权-前端
可以参考开放平台的JS-SDK授权文档
3、TOP授权-后端
可以参考开放平台的API授权文档
十、 权限控制
1、禁用cookie
TAE-Java禁用cookie，如使用，则会报异常，请注意。
2、权限控制
ISV在TAE容器中做权限控制较为简单，只要在项目的""根目录下放置"app.yml"文件，对某些页面所能访问的角色做判断即可，而不需要自己写登录逻辑等。
可能的配置如下图：
1. security:
2. - {url: /index,role: anonymous}
3. - {url: /env,role: sitecustomer}
4. - {url: /admin,role: developer}
安全和权限配置如下：
1. # url:需要授权的URL，凡是url配置起始的请求URL均需要相应的权限
2. # 例如配置：- {url: /admin,role: developer}
3. # 以下请求URL: /admin/abc和/admin/bcd 均需要developer权限
4.
5. # role:对应的权限控制，其中权限类型如下：
6. # anonymous：匿名权限
7. # sitecustomer：登录用户权限
8. # developer：开发者权限
特别提醒：线下SDK开发时，当请求URL权限不够时，将会跳至线下登录表单页面（线上容器不存在的）
十一、 前端规范
1、 U站应用规范
请参考U站应用前端规范
2、爱淘应用规范
请参考爱淘应用前端规范
3、微淘应用规范
请参考微淘应用前端规范
十二、 Q&A
1、如何咨询
如有任何关于TAE开发的问题，请首先参考我们的文档，如还有疑问，请咨询我们的技术开发；业务上的问题请咨询运营。
2、如何排错
请参考以下流程进行排错
3、框架支持
目前支持较好的框架有Spring、Webx、iBATIS，其它框架理论上也支持，如您在使用新的框架过程中遇到问题，欢迎反馈；
4、构建约束
1）、Ant构建方式
开发者如果使用Ant构建方式时，需要遵循以下限制规则：
l 任务（Task）限制
由于Ant构建在TAE平台内部构建，为了防止Ant 构建脚本在构建物理机器执行高风险的Task，提供以下Task白名单：
apt; attributenamespacedef; available; bindtargets; ccmreconfigure; componentdef; condition; copy; copypath; defaultexcludes; delete; diagnostics; ear; echo; filter; gunzip; gzip; jar; jarlib-available; jarlib-display; jarlib-manifest; jarlib-resolve; javac; jlink; jspc; local; macrodef; manifest; manifestclasspath; mkdir; move; native2ascii; patch; presetdef; projecthelper; property; propertyfile; propertyhelper; replace; replaceregexp; resourcecount; retry; sequential; style; sync; taskdef; tstamp; typedef; unjar; untar; unwar; uptodate; verifyjar; war; xmlproperty; xslt;
l 构建脚本限制
Ant构建脚本（build.xml)文件必须存放在应用工程的根目录，并且文件名称必须为“build.xml”
l 强制basedir路径限制
由于构建物理机器可能并行执行多个应用的构建任务，为了避免应用间相互影响，也防治恶意程序破坏系统环境，因此，JUAE构建系统将Ant构建脚本中project元素basedir属性值强制修改成当前工程目录的物理路径，应用自定义属性值被忽略。
例如，应用A的物理路径为/home/apps/project-a，其构建脚本文件build.xml定义如下：
|
<project name="HelloWorld" default="build" basedir="/home/target"> ... </project> |
其中，basedir="/home/target"将会被忽略，最终构建在物理路径/home/apps/project-a。
l 文件操作限制
与强制basedir路径限制的原则一样，限制文件操作的操作。总体而言，凡是文件相关操作的读写路径必须在在应用工程目录或其子目录下，否则，构建操作失败。
例如，应用A的物理路径为/home/apps/project-a，其构建脚本文件build.xml定义如下：
|
<?xml version="1.0" encoding="UTF-8" ?> <project name="HelloWorld" default="build" basedir="/home/target"> <property name="src" value="src"/> <property name="dest" value="/home/target/dest"/> <property name="hello_jar" value="hello1.jar"/> <target name="init"> <mkdir dir="${dest}"/> </target> ... </project> |
在任务中mkdir dir属性指向了${dest}，即创建路径为/home/target/dest的目录。明显地，/home/target/dest目录不为/home/apps/project-a的子目录。因此，在线上构建时，提示路径错误。
2）Maven构建方式
开发者如果使用Maven构建方式时，需要遵循以下限制规则：
l 不支持goal：install deploy
由于Maven构建在TAE平台内部构建，多个应用可能在相同机器上面构建，为了防止多个应用工程相互冲突（多个应用groupId、artifactId、version重复），同时也防止非法源码泄漏的问题（利用groupId、artifactId、version获取源码）。
未来很有可能支持ISV独立Maven仓库时，可以解除当前限制。
l 不提供官方的Maven仓库镜像
目前官方无法提供Maven仓库镜像
未来很有可能支持ISV独立Maven仓库时，可以解除当前限制。
l 不提供全局（通用）Maven settings.xml文件
目前实现不支持全局（通用）Maven settings.xml。ISV如果自行添加私有Maven仓库镜像配置到settings.xml文件中，会导致线下和线上的配置不一致，可能导致应用工程源码线上构建时，无法获取第三方依赖。
l Maven构建脚本文件（pom.xml）限制
Maven构建脚本文件（pom.xml）必须存放在应用工程的根目录下，并且文件名称必须为”pom.xml”。