Repository: 58code/Argo
Branch: master
Commit: 083e851e1ed4
Files: 19
Total size: 20.3 KB

Directory structure:
gitextract_z1elwqdy/

├── .gitignore
├── LICENSE.txt
├── README.md
├── plugin/
│   └── com.bj58.spat.plugins.argo_1.0.0.jar
├── pom.xml
└── samples/
    ├── company/
    │   ├── pom.xml
    │   └── src/
    │       └── main/
    │           ├── java/
    │           │   └── com/
    │           │       ├── bj58/
    │           │       │   └── argo/
    │           │       │       └── GroupConventionBinder.java
    │           │       └── mycompany/
    │           │           └── sample/
    │           │               └── controllers/
    │           │                   └── HomeController.java
    │           ├── resources/
    │           │   └── views/
    │           │       └── hello.html
    │           └── webapp/
    │               └── 1.html
    └── hello-world/
        ├── pom.xml
        └── src/
            └── main/
                ├── java/
                │   └── com/
                │       └── bj58/
                │           └── argo/
                │               └── controllers/
                │                   ├── HelloController.java
                │                   └── HomeController.java
                ├── resources/
                │   └── views/
                │       ├── index.html
                │       ├── post-upload.html
                │       └── post.html
                └── webapp/
                    ├── 1.html
                    ├── form.html
                    └── upload-form.html

================================================
FILE CONTENTS
================================================

================================================
FILE: .gitignore
================================================
/core/target
/samples/company/target
/samples/hello-world/target
/*.project
/core/*
/core/*.classpath
/core/*.project
/samples/company/.settings
/samples/company/bin
/samples/company/.classpath
/samples/company/.project
/samples/hello-world/.settings
/samples/hello-world/bin
/samples/hello-world/.classpath
/samples/hello-world/.project


================================================
FILE: LICENSE.txt
================================================
Copyright Beijing 58 Information Technology Co.,Ltd.

Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.


================================================
FILE: README.md
================================================
## 历史，动机(motivation)

Argo起源与[58同城]的内部web框架wf(web framework)。

目前wf支撑着[58同城]几乎所有的web站点，包括wap和手机端的访问等，现在wf每天处理10亿级的请求。经过长时间的运作与运行，证明wf是一个可靠的、高效的web框架。


作为一个有一定规模的互联网企业，如果在变化的互联网环境中上线一个项目，在软件开发中需要在三方面进行平衡：

1. 组织/公司，在一个组织内部，需要每个项目开发尽量有统一的风格、架构，学习成本、维护成本等尽可能低；
1. 运维，希望每个站点的配置和可执行部分分离，部署的方式相同；
1. 项目内部，希望程序员聚焦在业务上，可以快速实现产品需求、响应产品变化。
在此基础上，我们开发了wf。

Argo在wf做了大量优化和重构，以适应各组织软件开发的个性化需求，提升了系统性能，具有更好的可扩展性。Argo的开源反过来也促进wf2.0的开发。


## 哲学观 (philosophy)
1. [约定优于配置]，减少软件开发人员需做决定的数量，获得简单的好处，而又不失灵活性。Argo体系中有且只有一个组织级约定，规定包的命名，配置文件路径，日志文件路径等。组织的约定是不容侵犯，每个项目在组织级约定下工作。组织级约定建议以jar形式下发给各项目。
1. 简单，Argo可以不需要任何配置文件，项目代码结构简单，易于维护。
1. 纪律，包和类的命名都受组织级约定的控制，任何违反约定的行为可能导致系统无法正常运行。

## 系统特点 (features)

1. SEO友好的URL结构，Argo天然支持RESTful的url结构，并能自动匹配合适的参数；
1. 零配置，甚至你不要web.xml就能在tomcat上运行；
1. 插拔式组件架构，可以灵活扩张功能；
1. 高安全性，提供集群模式下，避免ip欺骗等功能。

## 系统约定 (convention)

Argo不是一个通用的web框架，一个问题解决方案可能有很多，但在Argo中只提供一种解决方案。Argo在以下约定中工作：

1. servlet 3.0环境，主要针对Tomcat 7.x；
1. 基于[guice]的Ioc，组织和项目可以各提供一个module注入模块，而且module的命名必须符合约定；
1. maven依赖，项目的代码体系和maven默认代码体系一致，maven以插件提供开发过程中所需要的开发运行环境（[jetty:run]或[tomcat7:run]）。

## Hello World

请参考例子 samples/hello-world

```shell
mvn tomcat7:run
```

或者
```shell
mvn jetty:run
```

然后浏览

http://localhost/

## 进阶

TODO

## 如何实现 (how)

TODO

## 更新日志
### 2013-03-21
1. 修正 issues #1, #2,
1. 修正 ContextPath不是根目录("/")下无法正常运行的bug
1. 提供model中默认参数 __beat,便于在view中使用
1. 提供war:war打包plugin实例，移除web.xml的依赖

```xml

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-war-plugin</artifactId>
  <version>2.3</version>
  <configuration>
    <failOnMissingWebXml>false</failOnMissingWebXml>
  </configuration>
</plugin>

```

[58同城]: http://www.58.com/
[约定优于配置]: http://zh.wikipedia.org/wiki/%E7%BA%A6%E5%AE%9A%E4%BC%98%E4%BA%8E%E9%85%8D%E7%BD%AE
[guice]: http://code.google.com/p/google-guice/
[jetty:run]: http://docs.codehaus.org/display/JETTY/Maven+Jetty+Plugin
[tomcat7:run]: http://tomcat.apache.org/maven-plugin-2.0/tomcat7-maven-plugin/run-mojo.html



================================================
FILE: pom.xml
================================================
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.bj58.spat</groupId>
    <artifactId>argo-project</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>pom</packaging>
    <modules>
        <module>core</module>
        <module>samples/hello-world</module>
        <module>samples/company</module>
    </modules>

    <name>58.com argo</name>
    <description>58.com argo</description>
    <url>https://github.com/58code/Argo</url>

    <organization>
        <name>58.com</name>
        <url>http://www.58.com/</url>
    </organization>

    <licenses>
        <license>
            <name>The Apache Software License, Version 2.0</name>
            <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
            <distribution>repo</distribution>
        </license>
    </licenses>


    <developers>
        <developer>
            <id>SPAT</id>
            <name>Service Platform Architecture Team</name>
            <url>https://github.com/58code</url>
            <email>spat@58.com</email>
        </developer>

        <developer>
            <id>renjun</id>
            <name>renjun</name>
            <url>http://weibo.com/duoway</url>
            <email>rjun@outlook.com</email>
        </developer>

        <developer>
            <id>liuzw</id>
            <name> liu zhongwei</name>
            <email>liuzw@58.com</email>
        </developer>
    </developers>

</project>


================================================
FILE: samples/company/pom.xml
================================================
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <groupId>com.bj58.spat</groupId>
    <artifactId>company-sample</artifactId>
    <version>1.0.0</version>
    <modelVersion>4.0.0</modelVersion>
    <packaging>war</packaging>

    <dependencies>
        <dependency>
            <groupId>com.bj58.spat</groupId>
            <artifactId>argo</artifactId>
            <version>1.0.0</version>
        </dependency>

        <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>javax.servlet-api</artifactId>
            <scope>provided</scope>
            <version>3.0.1</version>
        </dependency>

    </dependencies>

    <build>
        <plugins>


            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-war-plugin</artifactId>
                <version>2.3</version>
                <configuration>
                    <failOnMissingWebXml>false</failOnMissingWebXml>
                </configuration>
            </plugin>



            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>2.5.1</version>
                <configuration>
                    <source>1.6</source>
                    <target>1.6</target>
                    <encoding>UTF-8</encoding>
                </configuration>
            </plugin>

            <plugin>
                <groupId>org.apache.tomcat.maven</groupId>
                <artifactId>tomcat7-maven-plugin</artifactId>
                <version>2.0</version>
                <configuration>
                    <path>/</path>
                    <port>80</port>
                </configuration>
            </plugin>

            <plugin>
                <!-- http://wiki.eclipse.org/Jetty/Feature/Jetty_Maven_Plugin -->
                <groupId>org.mortbay.jetty</groupId>
                <artifactId>jetty-maven-plugin</artifactId>


                <configuration>
                    <stopPort>9966</stopPort>
                    <stopKey>foo</stopKey>
                    <scanIntervalSeconds>0</scanIntervalSeconds>
                    <connectors>
                        <connector implementation="org.eclipse.jetty.server.nio.SelectChannelConnector">
                            <port>80</port>
                            <maxIdleTime>60000</maxIdleTime>
                        </connector>
                    </connectors>
                    <webAppConfig>
                        <contextPath>/</contextPath>
                    </webAppConfig>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>2.5.1</version>
                <configuration>
                    <source>1.6</source>
                    <target>1.6</target>
                    <encoding>UTF-8</encoding>
                </configuration>
            </plugin>

        </plugins>
    </build>

</project>

================================================
FILE: samples/company/src/main/java/com/bj58/argo/GroupConventionBinder.java
================================================
/*
*  Copyright Beijing 58 Information Technology Co.,Ltd.
*
*  Licensed to the Apache Software Foundation (ASF) under one
*  or more contributor license agreements.  See the NOTICE file
*  distributed with this work for additional information
*  regarding copyright ownership.  The ASF licenses this file
*  to you under the Apache License, Version 2.0 (the
*  "License"); you may not use this file except in compliance
*  with the License.  You may obtain a copy of the License at
*
*        http://www.apache.org/licenses/LICENSE-2.0
*
*  Unless required by applicable law or agreed to in writing,
*  software distributed under the License is distributed on an
*  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
*  KIND, either express or implied.  See the License for the
*  specific language governing permissions and limitations
*  under the License.
*/
package com.bj58.argo;

import com.bj58.argo.convention.GroupConventionAnnotation;

/**
 *
 * 演示如何自定义组织策略
 *
 * @author Service Platform Architecture Team (spat@58.com)
 */
@GroupConventionAnnotation(
    groupPackagesPrefix = "com.mycompany"
)
public class GroupConventionBinder {
}


================================================
FILE: samples/company/src/main/java/com/mycompany/sample/controllers/HomeController.java
================================================
/*
*  Copyright Beijing 58 Information Technology Co.,Ltd.
*
*  Licensed to the Apache Software Foundation (ASF) under one
*  or more contributor license agreements.  See the NOTICE file
*  distributed with this work for additional information
*  regarding copyright ownership.  The ASF licenses this file
*  to you under the Apache License, Version 2.0 (the
*  "License"); you may not use this file except in compliance
*  with the License.  You may obtain a copy of the License at
*
*        http://www.apache.org/licenses/LICENSE-2.0
*
*  Unless required by applicable law or agreed to in writing,
*  software distributed under the License is distributed on an
*  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
*  KIND, either express or implied.  See the License for the
*  specific language governing permissions and limitations
*  under the License.
*/
package com.mycompany.sample.controllers;

import com.bj58.argo.ActionResult;
import com.bj58.argo.BeatContext;
import com.bj58.argo.annotations.Path;
import com.bj58.argo.controller.AbstractController;

/**
 * @author Service Platform Architecture Team (spat@58.com)
 */
@Path("hello")
public class HomeController extends AbstractController{

    @Path("")
    public ActionResult hello() {
        return writer().write("Hello world");
    }

    @Path("argo")
    public ActionResult helloArgo() {
        return writer().write("Hello, argo");
    }

    @Path("{name}")
    public ActionResult helloWorld(String name) {
        return writer().write("Hello, %s", name);
    }

    /**
     * 这个是一个比较复杂的例子，
     * Path中的路径可以用正则表达式匹配，
     * @Path("{phoneNumber:\\d+}")和@Path("{name}")的匹配顺序是
     * 如果都匹配，先匹配模板路径长的也就是@Path("{phoneNumber:\\d+}")
     *
     * @param phoneNumber
     * @return
     */
    @Path("{phoneNumber:\\d+}")
    public ActionResult helloView(int phoneNumber) {
        BeatContext beatContext = beat();

        beatContext
                .getModel()
                .add("title", "phone")
                .add("phoneNumber", phoneNumber);

        return view("hello");

    }
}


================================================
FILE: samples/company/src/main/resources/views/hello.html
================================================
<!DOCTYPE html>
<html>
<head>
    <title>$title</title>
</head>
<body>
这是一个demo，页面渲染采用velocity。
<h2>call me, $phoneNumber</h2>
</body>
</html>

================================================
FILE: samples/company/src/main/webapp/1.html
================================================
<!DOCTYPE html>
<html>
<head>
    <title></title>
</head>
<body>
aaaaa
</body>
</html>

================================================
FILE: samples/hello-world/pom.xml
================================================
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <groupId>com.bj58.spat</groupId>
    <artifactId>argo-hello-world</artifactId>
    <version>1.0.0</version>
    <modelVersion>4.0.0</modelVersion>
    <packaging>war</packaging>

    <dependencies>
        <dependency>
            <groupId>com.bj58.spat</groupId>
            <artifactId>argo</artifactId>
            <version>1.0.0</version>
        </dependency>

        <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>javax.servlet-api</artifactId>
            <scope>provided</scope>
            <version>3.0.1</version>
        </dependency>

    </dependencies>

    <build>
        <plugins>

            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-war-plugin</artifactId>
                <version>2.3</version>
                <configuration>
                    <failOnMissingWebXml>false</failOnMissingWebXml>
                </configuration>
            </plugin>

            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>2.5.1</version>
                <configuration>
                    <source>1.6</source>
                    <target>1.6</target>
                    <encoding>UTF-8</encoding>
                </configuration>
            </plugin>

            <plugin>
                <groupId>org.apache.tomcat.maven</groupId>
                <artifactId>tomcat7-maven-plugin</artifactId>
                <version>2.0</version>
                <configuration>
                    <path>/</path> <!--/argo -->
                    <port>80</port>
                </configuration>
            </plugin>

			<plugin>
				<!-- http://wiki.eclipse.org/Jetty/Feature/Jetty_Maven_Plugin -->
				<groupId>org.mortbay.jetty</groupId>
				<artifactId>jetty-maven-plugin</artifactId>
				
				
				<configuration>
				    <stopPort>9966</stopPort>
          			<stopKey>foo</stopKey>
					<scanIntervalSeconds>0</scanIntervalSeconds>
					<connectors>
						<connector implementation="org.eclipse.jetty.server.nio.SelectChannelConnector">
							<port>80</port>
							<maxIdleTime>60000</maxIdleTime>
						</connector>
					</connectors>
					<webAppConfig>
						<contextPath>/</contextPath>
					</webAppConfig>
				</configuration>
			</plugin>
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-compiler-plugin</artifactId>
				<version>2.5.1</version>
				<configuration>
					<source>1.6</source>
					<target>1.6</target>
					<encoding>UTF-8</encoding>
				</configuration>
			</plugin>

        </plugins>
    </build>

</project>

================================================
FILE: samples/hello-world/src/main/java/com/bj58/argo/controllers/HelloController.java
================================================
package com.bj58.argo.controllers;

import com.bj58.argo.ActionResult;
import com.bj58.argo.annotations.Path;
import com.bj58.argo.controller.AbstractController;

public class HelloController extends AbstractController {

    @Path("hello/{name}")
    public ActionResult hello(String name) {

        return writer().write("hello %s", name);

    }
}


================================================
FILE: samples/hello-world/src/main/java/com/bj58/argo/controllers/HomeController.java
================================================
// 包的命名规则受 GroupConvetionAnnotation.groupPackagesPrefix
package com.bj58.argo.controllers;

import com.bj58.argo.ActionResult;
import com.bj58.argo.BeatContext;
import com.bj58.argo.annotations.POST;
import com.bj58.argo.annotations.Path;
import com.bj58.argo.client.ClientContext;
import com.bj58.argo.client.Upload;
import com.bj58.argo.controller.AbstractController;
import com.google.common.base.Preconditions;
import com.google.common.base.Strings;

// 类的命名受 GroupConvetionAnnotation.controllerPattern约束
public class HomeController extends AbstractController {

    @Path("")
    public ActionResult home() {
//        System.out.println(1);
        return view("index"); // velocity模板是 /src/main/java/resources/views/index.html
    }

    @Path("post.html")
    @POST  // 只处理post的请求
    public ActionResult postForm() {

        BeatContext beat = beat();

        ClientContext client = beat.getClient();

        Preconditions.checkState(Strings.isNullOrEmpty(client.form("company")));
        Preconditions.checkState(Strings.isNullOrEmpty(client.form("address")));

        client.queryString("name");

        Preconditions.checkState(Strings.isNullOrEmpty(client.queryString("name")));
        Preconditions.checkState(Strings.isNullOrEmpty(client.queryString("phone")));
        Preconditions.checkState(Strings.isNullOrEmpty(client.queryString("submit")));


        beat.getModel()
                .add("company", client.queryString("company"))
                .add("address", client.queryString("address"))

                .add("name", client.form("name"))
                .add("phone", client.form("phone"))
                .add("submit", client.form("submit"));


        return view("post"); // resources/views/post.html velocity模板

    }

    /**
     *
     * 处理文件上传
     *
     */
    @Path("post-upload.html")
    @POST  // 只处理post的请求
    public ActionResult postUpload() {

        BeatContext beat = beat();

        ClientContext client = beat.getClient();

        Preconditions.checkState(Strings.isNullOrEmpty(client.form("company")));
        Preconditions.checkState(Strings.isNullOrEmpty(client.form("address")));
        Preconditions.checkState(Strings.isNullOrEmpty(client.form("file")));

        client.queryString("name");

        Preconditions.checkState(Strings.isNullOrEmpty(client.queryString("name")));
        Preconditions.checkState(Strings.isNullOrEmpty(client.queryString("phone")));
        Preconditions.checkState(Strings.isNullOrEmpty(client.queryString("submit")));
        Preconditions.checkState(Strings.isNullOrEmpty(client.queryString("file")));


        Upload upload = client.getUpload("file");


        beat.getModel()
                .add("company", client.queryString("company"))
                .add("address", client.queryString("address"))

                .add("name", client.form("name"))
                .add("phone", client.form("phone"))
                .add("submit", client.form("submit"))

                .add("upload", upload);



        return view("post-upload"); // resources/views/post-upload.html velocity模板

    }
}


================================================
FILE: samples/hello-world/src/main/resources/views/index.html
================================================
<html>
<head>
    <title>Argo sample page</title>
</head>
<body>
<h2>Samples</h2>
<ul>
    <li><a href="$__beat.servletContext.contextPath/hello/world">根据url获得参数的hello wolrd</a></li>
    <li><a href="$__beat.servletContext.contextPath/1.html">静态文件显示</a></li>
    <li><a href="$__beat.servletContext.contextPath/form.html">区分queryString和form参数</a></li>
    <li><a href="$__beat.servletContext.contextPath/upload-form.html">文件上传展示</a></li>
</ul>
</body>
</html>


================================================
FILE: samples/hello-world/src/main/resources/views/post-upload.html
================================================
<html>
<head>
    <title>form</title>
</head>
<body>
<h2>form post</h2>

<h3>upload file</h3>
<ul>
    <li>file name: $upload.fileName <i>注:调用 Upload.getFileName()实现,以下同理</i></li>
    <li>file size: $upload.size</li>
    <li>file contentType: $upload.contentType</li>
</ul>

<h3>queryString parameter</h3>
<ul>
    <li>company: $company</li>
    <li>address: $address</li>
</ul>
<h3>form parameter</h3>
<ul>
    <li>name: $name</li>
    <li>phone: $phone</li>
    <li>submit: $submit</li>
</ul>

<p>

处理的Action是 HomeController.postForm

</body>
</html>

================================================
FILE: samples/hello-world/src/main/resources/views/post.html
================================================
<html>
<head>
    <title>form</title>
</head>
<body>
<h2>form post</h2>
<h3>queryString parameter</h3>
<ul>
    <li>company: $company</li>
    <li>address: $address</li>
</ul>
<h3>form parameter</h3>
<ul>
    <li>name: $name</li>
    <li>phone: $phone</li>
    <li>submit: $submit</li>
</ul>

<p>

处理的Action是 HomeController.postForm

</body>
</html>

================================================
FILE: samples/hello-world/src/main/webapp/1.html
================================================
<html>
<body>
<b>bbbbbbbbbbbbbbbbbbb</b>
</body>
</html>

================================================
FILE: samples/hello-world/src/main/webapp/form.html
================================================
<!DOCTYPE html>
<html>
<head>
    <title></title>
</head>
<body>

<form method="post" action="post.html?company=58.com&address=beijing">
    <ul>
        <li>name: <input type="text" name="name"/></li>
        <li>phone: <input type="text" name="phone"/></li>
    </ul>

    <input type="submit" name="submit" value="提交"/>

</form>

<p>

这是一个表单提交页面<br/>
<i>action="post.html?company=58.com&address=beijing" </i><br/>
我们希望在post.html(对应的Action是HomeController.postForm())中能区分queryString和form的数据。

</body>
</html>

================================================
FILE: samples/hello-world/src/main/webapp/upload-form.html
================================================
<!DOCTYPE html>
<html>
<head>
    <title></title>
</head>
<body>


<form method="post" enctype="multipart/form-data" action="post-upload.html?company=58.com&address=beijing">
    <ul>
        <li>name: <input type="text" name="name"/></li>
        <li>phone: <input type="text" name="phone"/></li>
        <li>file:<input type="file" name="file"></li>
    </ul>

    <input type="submit" name="submit" value="提交"/>

</form>

<p>

    这是一个表单提交页面<br/>
    <i>action="post-upload.html?company=58.com&address=beijing" </i><br/>
    我们希望在post-upload.html(对应的Action是HomeController.postUpload())中能区分queryString和form的数据。



</body>
</html>